Designing Custom Entities in IFS Cloud: Getting It Right First Time

Best practices for designing custom entities in IFS Cloud — naming conventions, key patterns, relationship design, Marble integration, and future-proofing against upgrades.

IFSIFS CloudCustom EntitiesMarbleDatabaseArchitectureDevelopment

Custom entities in IFS Cloud are a powerful mechanism for extending the platform's data model, but designing them poorly creates technical debt that compounds at every upgrade cycle. Getting them right from day one requires discipline, clarity of purpose, and alignment with IFS Cloud's architectural principles.

This guide distills best practices from the IFS community, official documentation, and real-world deployments to help architects and senior developers make sound decisions when building custom entities.

Understanding Custom Entities in IFS Cloud

A custom entity in IFS Cloud is not simply a database table. It's a complete information object that exists at multiple layers:

Database table: Persisted data store in Oracle
Logical entity: IFS information model representation (with attributes, associations, and business logic)
Marble model: Low-code definition language for exposing the entity through APIs and UI
Projection: API surface and business logic interface for external consumers
UI controls: Pages, tabs, and configurations in Aurena

Each layer has its own naming conventions, design patterns, and constraints. Misalignment between layers is a common source of upgrade friction and technical debt.

When to Create a Custom Entity

Before designing, ask: Is a custom entity actually the right solution?

Create a custom entity when:

You need to store persistent data that doesn't exist in standard IFS entities
The data is central to your business process and requires audit trails, state management, or referential integrity
You plan to expose the entity via APIs to other systems or UI pages
You need complete control over the data lifecycle

Don't create a custom entity if:

You only need to add fields to an existing standard entity (use custom attributes instead)
You're temporarily staging data before importing into a standard module (use utility models without database persistence)
You need read-only calculated fields (use queries and projections with virtual attributes)

This distinction is critical: IFS Cloud discourages customizations of its platform modules. Custom entities should augment, not alter, the core system.

Naming Conventions: The Foundation of Maintainability

Poor naming creates confusion that persists for years. IFS naming standards serve a purpose—they enforce consistency across hundreds of developers and dozens of upgrade cycles.

Entity Names

Follow mixed-case, descriptive nouns:

✓ SupplierQualification
✓ CustomerCertification
✓ AssetMaintenanceLog
✗ SupQual (cryptic abbreviations)
✗ supplier_qualifications (database naming in the wrong context)

Key rules:

No underscores, spaces, or special characters
Must be unique across the entire IFS application
Should describe the business concept, not the implementation
Avoid generic names that suggest scope beyond the actual content (e.g., AssetLog rather than just Log)
Expand obvious abbreviations (e.g., CustomerOrderReservationType instead of CustOrdReservationType)

When extending existing logical units, keep the name consistent with the established domain language. If creating a related but separate concept, prefix with clarity:

GoodMat: CustomerProfile, PartnerProfile, EmployeeProfile (clear scope)
BadMat: Profile, Profile, Profile (ambiguous; requires context every time)

Database Naming

The underlying database table follows uppercase with underscores:

Entity Name: SupplierQualification
Table Name: SUPPLIER_QUALIFICATION

Database naming rules (Oracle constraints):

Maximum 30 characters
Uppercase letters A-Z, underscores, digits 0-9
Must not conflict with SQL reserved words (FROM, SELECT, ORDER, etc.)
Must not begin with reserved word prefixes (ALL*, DBA*, USER_, etc.)
Words delimited by single underscores

Column Naming

Columns also use uppercase with underscores and must:

Describe the attribute in singular form
Avoid repeating the table name (SUPPLIER_QUALIFICATION.QUALIFICATION_ID is redundant; use SUPPLIER_QUALIFICATION.ID)
Not conflict with SQL reserved words

Good: SUPPLIER_QUALIFICATION.ID, SUPPLIER_QUALIFICATION.STATUS, SUPPLIER_QUALIFICATION.CERTIFIED_DATE
Avoid: SUPPLIER_QUALIFICATION.SUPPLIER_QUALIFICATION_ID (redundant nesting)

Marble and Projection Naming

In Marble definitions and projections, use mixed-case again to align with IFS standards:

Entity associations and projections inherit the entity naming convention:

✓ SupplierQualificationAnalysis (descriptive projection)
✓ QualificationHistory (association within SupplierQualification)
✗ data (vague)

Primary Key Design Patterns

The primary key is the contract between your entity and the rest of IFS Cloud. Bad key design breaks referential integrity, complicates associations, and creates performance issues.

Surrogate vs. Business Keys

Surrogate Key (Recommended): Use an auto-generated, system-managed unique identifier. This is IFS Cloud's default pattern.

Advantages:

Immutable and database-agnostic
Simplifies joins and associations
Allows business key changes without cascading updates
Aligns with IFS Cloud conventions

Business Key Combinations: When a logical primary key exists naturally (e.g., supplier + qualification code), create a unique constraint (alternate key), not the primary key:

When to Use Composite Business Keys: Only if the entity is genuinely ephemeral and used in narrow, internal contexts. In almost all other cases, the complexity of managing multi-column keys outweighs the theoretical benefit.

Objid and Objversion

IFS Cloud automatically maintains Objid (unique object ID) and Objversion (optimistic locking version) on all custom entities. These are system attributes—do not override them or use them in your application logic.

The Objversion is combined with Objid in the ETag header for REST APIs, preventing "mid-air collision" bugs when concurrent updates occur:

ETag: Base64(Objid + Objversion)

This means your API layer automatically enforces optimistic locking. Leverage it instead of building your own version control.

Relationship Design Patterns

Custom entities rarely exist in isolation. They reference standard entities, belong to parent structures, or support child collections. How you model these relationships determines API usability, data integrity, and upgrade resilience.

Association Types

Reference Association (Many-to-One): Your custom entity holds a foreign key to another entity. This is the most common pattern.

Marble automatically creates a foreign key constraint in the database and exposes the association in APIs. This reference is non-nullable by default if marked as mandatory.

Child Array (One-to-Many): A parent entity contains many children. Use array associations sparingly and only when the children are logically owned by the parent.

Marble generates the reverse foreign key on QualificationStep pointing back to SupplierQualification.

Important: Array associations create implicit delete cascades. If you delete a SupplierQualification, all QualificationSteps are deleted. This is often not desired. Use standalone entities with references instead:

Referential Integrity

Always include explicit foreign key constraints in Marble:

Never rely on application code to maintain referential integrity. The database enforces it; application logic merely respects it.

Nullable vs. Mandatory

Make fields mandatory only when they are truly required by the business. Optional fields reduce friction and support partial data entry workflows.

Marble Entity Definition: Syntax and Structure

Marble is IFS Cloud's domain-specific language for defining entities, logic, and integrations. It's compiled into Java handlers, database DDL, and API definitions.

Basic Entity Template

Key Marble Features for Custom Entities

Virtual Attributes: Computed fields that are not persisted but calculated on retrieval:

Virtual attributes reduce storage but increase query cost. Use for UI-only display fields, not for heavy calculations in APIs.

Readonly Attributes: System-generated fields like ID, creation timestamps, and Objversion:

Default Values: Provide sensible defaults to reduce NULL handling:

Constraints: Mark mandatory fields explicitly:

Enumerations and Lookup Values

Define enumerations for fixed-value fields instead of text or numeric codes:

Don't create lookup entities for small, static enumerations. Enumerations are cleaner, performant, and easier to manage. Use lookup entities only for frequently changing, large, or user-configurable lists.

Indexing and Query Performance

Custom entities are often queried by hundreds of concurrent users. Indexing strategy directly impacts API response times and database load.

Primary Key Index

Marble automatically creates the primary key index:

Index Name: ENTITY_NAME_PK
Columns: Primary key column(s)

Secondary Indexes

Define indexes for:

Foreign key columns: Always indexed to support joins
Frequently filtered columns: Status, date ranges, boolean flags
Sort columns: Fields commonly used in ORDER BY

Indexing Pattern (Database Level)

Indexing Guidelines:

Index foreign keys always
Index columns in WHERE clauses (top 3-5 most-filtered)
Index columns in ORDER BY clauses
Don't index text columns with high cardinality unless text search is essential
Composite indexes should follow query patterns: equality first, then range conditions

Marble and Projection Configuration

Marble defines the data model; Projection Configuration (via the IFS Cloud UI) exposes it via APIs and business logic.

Creating a Projection

A projection is the API surface for your entity. Every custom entity needs at least one projection to be usable in pages or integrations.

Entity Associations in Projections

If your custom entity has child records or references to other custom entities, create explicit associations:

This allows API consumers to expand and drill into related data:

GET /api/supplier-qualifications/123?$expand=children,supplier

Custom Actions and Events

Projections can define custom actions (method endpoints) and subscribe to entity events:

Future-Proofing Against Upgrades

IFS Cloud is on an "evergreen" release cycle, with updates every 6-12 weeks. Custom entities must be designed to survive these upgrades without breaking.

The No-Modifications Principle

IFS's core principle: Never customize anything in a platform module. Custom entities are extensions, not modifications.

This means:

Do not modify IFS-provided entities (they will be overwritten in upgrades)
Do not add custom tables to standard modules (create standalone custom entities instead)
Do not override system-generated handlers or projections
Do not mark custom projections as "Premium API"—that's reserved for IFS

Column Addition and Schema Evolution

IFS Cloud supports adding columns to custom entities. When you add a new persistent field:

Create the column with sensible defaults or nullable=true
Backfill existing data via a data migration script
Test thoroughly in a lower environment before production

The upgrade process will:

Add the column to the database
Create the attribute in the Marble model
Update projections automatically

Renaming, Removing, or Modifying Columns

These operations require manual intervention:

Rename: Not automatically supported; you'll need a custom migration SQL script
Remove: Drop support in one release, then remove the column in the next
Change type: Complex; may require new column + migration + deprecation cycle

Best practice: Make column decisions carefully the first time. Once deployed, the column lives for years.

Handling Deleted Standard Entities

If a standard IFS entity you reference is deprecated:

IFS communicates the deprecation 6-12 months in advance
You have time to refactor your custom entities to reference a replacement
Use a phased migration: create a new reference, migrate data, retire the old reference

Data Migration and Backup

Before every upgrade:

Export all custom entity data
Snapshot custom entity definitions (Marble, projections, configurations)
Test the upgrade in a clone environment
Validate data integrity post-upgrade
Plan any custom data cleanup or migration

IFS Cloud provides upgrade tooling to detect schema conflicts early.

Anti-Patterns: What to Avoid

1. Storing Data in Multiple Places

✗ Store data in custom entity AND replicate to standard table
✗ Sync data between custom entity and another system via polling
✓ Single source of truth; integrate at API boundaries

Duplication creates synchronization debt and is the root of many upgrade failures.

2. Over-Normalizing or Under-Normalizing

✗ Create 20 tiny entities with complex joins (over-normalized)
✗ Store all data in one denormalized blob (under-normalized)
✓ 3NF: Dependencies on the key, the whole key, and nothing but the key

IFS Cloud queries are projection-based, not arbitrary SQL. Denormalization is handled at the projection layer, not the entity layer.

3. Virtual Attributes in Queries

✗ Define complex virtual attributes and filter by them
  (virtual fields can't be indexed; queries become slow)
✓ Persist derived data or compute it at the projection level

4. Circular References

✗ Entity A → Entity B → Entity C → Entity A
✓ Unidirectional references; use projections for complex queries

5. Ignoring Objversion

✗ Manage concurrency with a custom "last_modified_date" column
✓ Rely on Objversion + ETag for optimistic locking

6. Creating Utility Entities as Persistent Tables

✗ entity TransactionTempData { ... } with database persistence
✓ Use in-memory structures or staging tables in temporary schemas

7. Tight Coupling to Other Custom Entities

✗ Entity A assumes Entity B exists (breaks module reusability)
✓ Loose coupling via references; entities should be independently deployable

Indexing Strategy and Performance Tuning

After your custom entity is live, monitor performance. IFS Cloud provides execution statistics for projections.

Query Performance Checklist

All foreign key columns are indexed
Frequently filtered columns (status, date, flag) are indexed
Composite indexes match query patterns (equality columns first, then range)
Index cardinality is high (> 10% of table rows)
Indexes are not on columns with < 100 distinct values (ROW_ID works better)
No unused indexes (they slow INSERT/UPDATE)

Example Performance Analysis

SELECT COUNT(*) FROM SUPPLIER_QUALIFICATION;  -- 500,000 rows
SELECT * FROM SUPPLIER_QUALIFICATION
  WHERE STATUS = 'ACTIVE' AND CREATED_DATE > SYSDATE - 30;  -- 10,000 rows

-- Query explains why it's slow:
-- Table scan (full scan of 500K rows), then filter
-- Solution: Composite index on (STATUS, CREATED_DATE)

Configuration Best Practices

Entity Lifecycle and State Management

If your entity has a lifecycle (DRAFT → ACTIVE → ARCHIVED), define states explicitly:

Audit and Logging

Custom entities should track:

IFS Cloud automatically populates these fields via the application context.

Security and Role-Based Access

Define projections with security filters:

Users see only their own records unless they have the ADMIN role.

Testing Strategy

Unit Testing

Test Marble handlers independently:

Integration Testing

Test projections and API behavior:

GET /api/supplier-qualifications?filter=status:eq:ACTIVE
  → Returns only ACTIVE qualifications
  → Respects security filters
  → Supports $expand for associations

Data Migration Testing

If adding or removing columns, test the migration in a non-production clone first.

Key Takeaways

Name deliberately: Mixed-case entity names, uppercase database tables, and consistent patterns across all layers
Use surrogate keys: Auto-generated IDs simplify references and support entity evolution
Create associations carefully: Prefer references to array relationships; understand cascade implications
Leverage Marble fully: Define entities, enumerations, virtual attributes, and handlers in Marble; let it generate SQL and API code
Index strategically: Primary key + foreign keys + top 3 frequently-filtered columns
Respect Objversion: Let IFS Cloud handle optimistic locking automatically
Avoid tight coupling: Entities should be deployable independently
Design for upgrade readiness: Minimize schema changes; use projections for flexibility
Test comprehensively: Unit, integration, and data migration tests before production
Monitor performance: Track projection execution times and index usage; tune post-deployment

Custom entities, when designed well, are elegant extensions to IFS Cloud that scale gracefully through upgrades. When designed poorly, they become sources of friction that compound over years. The upfront investment in naming, architecture, and relationship design pays dividends in maintainability, performance, and upgrade resilience.