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

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:

• Entity model: The XML-backed .entity source or configured custom-entity definition that owns attributes, keys, persistence and references
• Generated database artefacts: Table, view, packages and metadata produced by the IFS toolchain where the entity is persistent
• Layered server logic: Generated and customer-owned .plsql behaviour for validation and business operations
• Projection: Marble API surface for the web client and integrations
• 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 the supported migration/staging mechanism for the chosen tool and environment)
• You need read-only calculated fields (use queries and projections with virtual attributes)

This distinction is critical. Start with configuration and standard extension points; use source development for durable behaviour that cannot be expressed safely through configuration. A configured custom entity and a source-developed entity are different delivery choices, so decide ownership, lifecycle and update testing before modelling either.

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

Good: CustomerProfile, PartnerProfile, EmployeeProfile (clear scope)
Avoid: Profile (too ambiguous without its owning domain)

Generated Database Naming

IFS generation normally derives uppercase Oracle object names from the model, often with conventional suffixes for tables, views and packages. Treat the generated result as authoritative:

Entity Name: SupplierQualification
Generated family: SUPPLIER_QUALIFICATION_TAB / SUPPLIER_QUALIFICATION / SUPPLIER_QUALIFICATION_API

Database naming rules (Oracle constraints):

• Object-length limits depend on the Oracle/database and IFS release, so follow Developer Studio validation rather than a hard-coded universal 30-character rule
• Uppercase letters A-Z, underscores, digits 0-9
• Must not conflict with SQL reserved words (FROM, SELECT, ORDER, etc.)
• Avoid names that look like Oracle dictionary objects or IFS framework internals (for example, DBA_... or USER_...)
• Words delimited by single underscores

Attribute and Column Naming

Model attributes use the entity-model naming convention and generation derives database column names. Attributes should:

• Describe the attribute in singular form
• Follow the key and naming pattern used by the owning component; do not rename a meaningful QualificationId to generic Id merely to avoid repetition
• Not conflict with SQL reserved words

Good model names: QualificationId, Status, CertifiedDate
Avoid: Id1, Code2, TemporaryValue

Entity Model, Marble, and Projection Naming

Entity and enumeration definitions are XML-backed Developer Studio models, not the inline Marble DSL shown in many generic examples. Projection and client sources use Marble. A minimal projection over an already-modelled entity looks like:

Use category Users for an interactive IFS Cloud Web projection. If the contract is intended for an external integration, classify and secure an integration projection according to the target release's API-governance rules rather than assuming the same projection should serve every consumer.

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: Use an auto-generated identifier when the record has no stable business identity or when an immutable technical identity materially simplifies integrations. Configure or model the key through the supported entity tooling; do not paste an invented inline entity block into a projection.

Advantages:

• Immutable and database-agnostic
• Simplifies joins and associations
• Allows business key changes without cascading updates
• Can be appropriate for a customer-owned aggregate with no natural identifier

Business Key Combinations: Composite business keys are common in IFS and can be the right contract when the components are stable, meaningful, and already used by the surrounding domain—for example, supplier plus qualification code. Model uniqueness explicitly using the capabilities available for the entity type; IFS does not automatically create an alternate unique constraint because two ordinary attributes appear beside a surrogate key.

When to Use Composite Business Keys: Use them when they reflect the established IFS domain and will not change. Avoid them when one component is mutable, excessively long, or supplied by an external system whose identifiers can be reassigned. The decision is contextual, not a universal “surrogate keys first” rule.

For the running example, document the decision before opening Developer Studio:

Whichever primary key you choose, enforce the business duplicate rule on the server. A client-side duplicate check is useful feedback but is race-prone under concurrent creation.

Objid and Objversion

Generated IFS entity views commonly expose object identity and version metadata used by the framework, and projection entities can publish an ETag for optimistic concurrency. Do not invent, persist, or decode those values yourself. Inspect the deployed projection $metadata and response payload/headers: whether an entity requires If-Match, and the exact ETag representation, belongs to that generated contract. Preserve the ETag returned by a read and send it on updates where the service requires it.

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 the target entity's key attributes and models a reference to it. This is the most common pattern; the generated solution may enforce it with business logic, a database constraint, or both.

Model the source key attributes and the reference in the .entity model. When the relationship is published in a projection, its Marble shape is key-based:

Use the actual target entity and complete key from Developer Studio. Projection metadata creates a navigation relationship; it does not by itself prove that a physical foreign-key constraint exists or that the target is mandatory. Those decisions belong in the entity model and generated database design.

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.

After modelling a child entity with the parent's complete key, publish the collection with an array mapping:

An array exposes navigation; it does not automatically guarantee a database delete cascade. Define deletion and orphan behaviour explicitly in the entity/business logic and test it. For governed records, a cancel/archive transition is often safer than physical parent deletion.

Referential Integrity

Model the relationship explicitly and use the generated referential rules supported for that entity. Do not assume that adding a projection reference creates an Oracle foreign key. IFS business relationships sometimes require application validation because installation order, optional components, state, or cross-domain rules make a physical constraint inappropriate.

Nullable vs. Mandatory

Set optionality in the entity model and reinforce it in server validation. In the projection, data-item properties such as required = [true] describe the service contract, but they are not a substitute for the persistent model.

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

Entity Source and Projection Structure

Marble is used for projection and client models. The entity itself is an XML-backed .entity model maintained with Developer Studio, while enumerations use .enumeration models and server behaviour uses generated/layered .plsql source.

A Practical Source Set

A source-developed entity normally involves:

Names and generated-file placement vary with the component and release; create them with Developer Studio rather than hand-writing XML.

Calculated Attributes

Decide where a calculation belongs:

• In the entity model when it is part of the reusable business object
• In projection source when it exists only in one service contract
• In a query/reporting source when it is analytical and read-only
• Persisted when the value is historically significant and must not change when source data changes

A projection-specific fetched item can look like:

Confirm the generated database column names and null behaviour. Calculated expressions can be expensive when filtered or sorted over large sets, so measure the actual query plan and service response.

Read-only and Required Behaviour

Persistent mandatory/default rules belong in the entity model and server logic. Assuming ReviewComment already exists in the entity model, projection properties can shape its service contract:

Client editable and required expressions guide interaction but do not enforce API calls. Validate authoritative rules on the server.

Enumerations and Lookup Values

Define fixed-value domains in an .enumeration model, including stable database values and translatable client values, then use that type from the entity model. Do not declare the enumeration with an invented inline projection block.

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 can become high-volume operational objects. Indexing strategy affects API response time and write cost, but it must follow measured query patterns and be delivered through the supported entity/source model.

Primary Key Index

Generation creates the key constraints and supporting database structures required by the entity model. Inspect the generated installation source for the exact names rather than relying on a universal ENTITY_NAME_PK pattern.

Secondary Indexes

Define indexes for:

1. Reference key columns: Consider an index where joins, delete checks, or lookups make it useful

   Model the index in the supported entity/source tooling; do not add it manually to a managed environment.

2. Frequently filtered columns: Status, date ranges, boolean flags

   A low-cardinality status alone may be a poor index, while status plus a selective date/site predicate may be valuable.

3. Sort columns: Fields commonly used in ORDER BY Sorting does not automatically justify an index; check selectivity, leading columns, page size, and whether filtering uses the same access path.

Indexing Pattern (Database Level)

For a common query such as “active qualifications for one supplier since a date,” an index beginning with the supplier key and then the selective equality/range columns may be a candidate. Prove it with representative data and an execution plan, add it to the customer solution using the release-supported index model, and test write overhead. Do not execute ad hoc CREATE INDEX against IFS-owned or generated tables.

Indexing Guidelines:

• Consider reference keys used by joins and delete checks
• Index recurring selective access paths, not every column appearing in a filter
• Treat ordering as one part of the complete filter/order/paging plan
• Do not infer index value from datatype or cardinality alone
• Composite indexes should follow query patterns: equality first, then range conditions

Marble and Projection Configuration

For source development, the entity model defines the data object and a .projection Marble file publishes the API. Projection Configuration is a separate configuration capability used to extend supported projection contracts; it is not the source entity designer.

Creating a Projection

A projection is the API surface for your entity. A source-developed entity needs at least one suitable projection to be usable in an IFS Cloud Web page or OData integration; a configured custom entity can instead be exposed through the release's generated/configured projection capabilities.

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 .../SupplierQualificationHandling.svc/SupplierQualifications(...)?$expand=QualificationSteps,SupplierRef

Discover the real service base path, key literal, navigation-property names, and ETag rules from API Explorer and $metadata.

Custom Actions and Events

Projections can define bound actions for state-changing operations and functions for read-only results:

Generate the action scaffold and implement it in the owning layered .plsql source. The bound entity key is implicit. Entity lifecycle behaviour belongs in generated entity methods, state events, workflows, or supported application-event mechanisms—not inline on Create/on Update blocks in projection source. Projection actions own their transaction, so do not add manual commits.

Configuration or Source Development?

IFS Cloud can store customer-owned data through configuration capabilities as well as through source-developed customer components. Choose the smallest route that still gives the business object a safe lifecycle.

Prefer a Configured Custom Entity When

• The attributes, references, and maintenance UI fit the supported custom-object capabilities.
• The process needs straightforward CRUD rather than a rich state machine.
• Configuration ownership and promotion are already governed.
• The expected volume and integration use stay within the documented limits for the target release.

Configured does not mean disposable. Export the definition through the supported configuration package process, version it, test its permission model, and include it in update analysis.

Prefer Source Development When

• The entity owns non-trivial transactional business behaviour.
• It needs generated/layered PL/SQL, state events, or several bound actions.
• It forms a reusable service contract for pages and integrations.
• It belongs to a customer component with an established build and regression suite.
• Its performance or data lifecycle requires model features unavailable in configuration.

Do not switch to source merely to obtain direct SQL access. Source development is still model-driven and must pass through the IFS build and delivery process.

Security Design Before UI Design

Write the access matrix before publishing the projection:

Translate that matrix into projection/entity/action grants in permission sets. Then apply the business-data scope needed for supplier, company, site, or other domain context. Test each negative combination directly through the API; a hidden client command is not security.

Sensitive attributes deserve a separate decision. If a broad page needs the entity but only a narrow role needs a confidential note, consider a separate projection/operation contract rather than relying on every client to hide the field.

Build and Delivery Workflow

For a source-developed entity:

1. Validate the entity and enumeration models in the release-aligned Developer Studio.
2. Generate server source and inspect every generated warning.
3. Add the smallest projection, then validate its $metadata contract.
4. Add client source only after the service works.
5. Commit source and tests to the customer solution repository.
6. Create the build in IFS Lifecycle Experience/Build Place.
7. Deliver to a non-production environment and apply permission sets/configuration.
8. Run migration, API, UI, concurrency, performance, and recovery tests.
9. Promote the same immutable build through the governed release route.

For IFS-managed Cloud, do not add tables, columns, constraints, or indexes by connecting as an application owner. The model and delivery are the reproducible source of truth.

Data Lifecycle and Retention

Define what happens after a qualification expires, a supplier is removed, or a legal retention period ends. Decide whether the record is cancelled, archived, anonymised, or physically deleted; who can trigger it; and what related history must remain.

Also define:

• how the entity is seeded or migrated;
• how duplicate business keys are rejected;
• how failed imports are reconciled;
• how attachments and document references are retained;
• how integrations learn that a record was cancelled or deleted;
• which supported export or recovery evidence proves the data can be recovered.

These decisions affect keys, indexes, actions, events, APIs, and reporting. Retrofitting them after production data exists is far more expensive than modelling them first.

Future-Proofing Against Upgrades

IFS Cloud receives service and release updates under the customer's supported lifecycle. Cadence and available deferral windows vary by service/update type and contract. Custom entities must be designed and regression-tested for each target update.

The No-Modifications Principle

Prefer configuration, extension, and customer-owned source over modifying IFS-delivered Core source. Sometimes a justified customer-layer override or overtake is the supported source-development mechanism; keep it narrow and review it with Update Analyzer.

This means:

• Do not hand-edit generated or IFS-delivered Core artefacts
• Do not create ad hoc database tables outside the model/delivery process
• Use supported customer-layer overrides only when configuration or a standalone customer entity cannot meet the requirement
• Classify projection consumers using supported categories and API governance for the target release; do not invent or copy internal product classifications

Column Addition and Schema Evolution

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

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

Add CertificationRenewalDate through the configured custom-attribute/custom-entity UI or the Developer Studio entity model, according to the entity's ownership. Make it nullable initially or provide a business-safe default and migration.

Generation and delivery will:

• Add the column to the database
• Regenerate the entity/database artefacts and metadata from the updated entity model
• Regenerate affected projections and clients; a new entity attribute is not automatically part of every deliberately narrowed projection

Renaming, Removing, or Modifying Columns

These operations require manual intervention:

• Rename: Treat as a compatibility/data migration; use supported delivery and migration tooling rather than ad hoc SQL against managed Cloud
• Remove: Deprecate API/UI use first, then remove the column after the agreed compatibility and data-retention window
• 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:

1. Review IFS release notes, Update Analyzer output, and the target release's model changes
2. Plan against the actual removal/change notice rather than assuming a universal deprecation window
3. Use a phased migration: create a new reference, migrate data, retire the old reference

Add the replacement key/reference alongside the old one, migrate and reconcile data, update projection/client consumers, then retire the old contract only after all callers have moved.

Data Migration and Backup

Before every upgrade:

1. Confirm backup/recovery coverage for the environment and take any customer-managed export required by the agreed recovery plan
2. Version entity, enumeration, projection, client, server source, and exported configuration in the customer solution/change record
3. Test the upgrade in a clone environment
4. Validate data integrity post-upgrade
5. Plan any custom data cleanup or migration

Use IFS Lifecycle Experience, Update Analyzer/Configuration Analyzer where applicable, build validation, and a realistic non-production update rehearsal to detect conflicts early. IFS-managed backup and restore remains an operational service; customers should not invent a database snapshot procedure outside it.

Anti-Patterns: What to Avoid

1. Storing Data in Multiple Places

✗ Store data in custom entity AND replicate to standard table
✗ Let two systems update the same business fact without ownership or reconciliation rules
✓ Define a system of record and integrate through a governed API/event/batch contract

Duplication creates synchronisation debt. Polling can still be a valid integration pattern when its latency, idempotency, cursor, retry, and reconciliation behaviour are deliberate.

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

Clients consume projection contracts, while generated entity and query implementations still execute against Oracle. Use projection/query models for read shapes where appropriate, but do not force every analytical denormalisation into an operational entity.

3. Virtual Attributes in Queries

✗ Publish an expensive calculated expression as a default filter/sort path
  without measuring the generated SQL and supported indexing options
✓ Use a fetched/projection calculation for light display-only values
✓ Persist or build a supported read model when selective filtering must be indexed

A fetched projection item is not automatically slow, and Oracle can support some expression-based access paths. The design question is whether IFS generation and the target operating model support the required index/read model and whether the complete query remains selective with representative data. Measure rather than applying a blanket rule.

4. Circular References

✗ Create circular component dependencies or unbounded nested expansions
✓ Declare one owning direction and publish only the navigation paths consumers need

Two-way business relationships are not automatically wrong. The risk is an installation dependency cycle, ambiguous lifecycle ownership, or an API that recursively expands a large graph.

5. Ignoring Objversion

✗ Ignore the ETag published by a projection update contract
✓ Preserve the returned ETag and send `If-Match` where `$metadata` and the service require optimistic concurrency

6. Creating Utility Entities as Persistent Tables

✗ Add a permanent customer entity solely because an import needs temporary working data
✓ Use the supported staging/import mechanism of Data Migration Manager, migration jobs, External Files, or the selected integration tool

7. Tight Coupling to Other Custom Entities

✗ Entity A silently assumes an optional component is installed
✓ Declare required component dependencies, or use a dynamic component dependency only where the feature can genuinely operate without that component

Indexing Strategy and Performance Tuning

After your custom entity is live, monitor it with the application, database, and service telemetry available for the customer's operating model. IFS-managed Cloud does not give customers unrestricted database diagnostics, so use supported logs and engage IFS Support when deeper platform evidence is required.

Query Performance Checklist

• Recurring selective reference/filter paths have suitable supported indexes
• Low-cardinality status/flag indexes are justified by the complete access path
• Composite indexes match query patterns (equality columns first, then range)
• Selectivity and clustering have been measured with representative data rather than a fixed percentage rule
• The plan uses the intended leading columns for equality, range, sorting, and paging
• No unused indexes (they slow INSERT/UPDATE)

Example Performance Analysis

SELECT COUNT(*) FROM supplier_qualification;  -- 500,000 rows
SELECT qualification_id, supplier_id, status, created_date
  FROM supplier_qualification
  WHERE STATUS = 'ACTIVE' AND CREATED_DATE > SYSDATE - 30;  -- 10,000 rows

-- Capture the actual execution plan and predicate selectivity.
-- A full scan may be correct for 10,000 widely distributed rows.
-- If normal requests also filter by supplier/site, that leading key may be
-- more useful than a low-cardinality STATUS-first index.

Run diagnostic SQL only in an environment and account where database access is supported. Deliver any index through the entity/customer solution—not as an untracked production statement.

Configuration Best Practices

Entity Lifecycle and State Management

If your entity has a lifecycle (Draft → Active → Archived), model a state machine in the entity source and generate the corresponding PL/SQL behaviour. Expose supported transitions as bound projection actions. Do not represent the lifecycle as a freely editable text/enumeration field or an invented Java-style handler block.

The server transition must lock or check the current version, validate the source state and caller, call any required standard business APIs, and let the projection framework commit or roll back the complete action.

Audit and Logging

Decide audit requirements from the business and regulatory process. Generated entity metadata supplies framework identity/version information, but it does not mean every invented CreatedDate, CreatedBy, LastModifiedDate, and LastModifiedBy attribute is automatically created and populated. Model required audit attributes explicitly or use the standard history/audit mechanism appropriate to the component.

Security and Role-Based Access

Projection permission sets control access to entities, CRUD, actions, and functions. They do not provide a generic inline security { userHasRole(...) } row-filter DSL. Business-data access must use the standard company/site/project/access-control model of the domain or explicit supported server-side validation for the customer entity. Test an out-of-scope user against the API as well as the page.

Testing Strategy

Unit Testing

Test the generated/layered PL/SQL with the team's approved database-test harness where available, and test the published projection contract with OAuth in a disposable non-production dataset. There is no generic generated Java SupplierQualificationHandler API for an ordinary PL/SQL-backed IFS Cloud entity.

Integration Testing

Test projections and API behavior:

GET .../SupplierQualificationHandling.svc/SupplierQualifications
    ?$filter=Status eq 'Active'&$top=20
  → Uses the exact property/value representation from $metadata
  → Returns only data in the test user's business scope
  → Expands only navigation properties published by the projection

Data Migration Testing

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

Minimum Promotion Test Matrix

Do not stop at “create, open, edit.” A custom entity becomes a reusable platform contract, so test its lifecycle and failure behaviour across every supported entry point:

Use at least two permission identities: one with the intended maintenance rights and one deliberately outside the data/operation scope. Run the negative tests against the API as well as IFS Cloud Web. A field hidden by client configuration, a disabled command, or a filtered selector is not a server authorisation result.

For volume-sensitive entities, seed representative key distribution and history depth before measuring. A few hundred evenly distributed rows will not expose a status/date filter that degrades after three years of production data. Record response-time and generated-query evidence for the critical list, detail, reference lookup, and batch/integration paths so a later update can be compared to a real baseline.

Key Takeaways

1. Name deliberately: PascalCase model names, generated uppercase database objects, and consistent patterns across all layers
2. Choose keys deliberately: Use a stable business/composite key or a surrogate based on the domain and integration contract
3. Create relationships carefully: Map complete keys and define integrity/deletion behaviour rather than assuming projection arrays cascade
4. Use each source model correctly: Entity/enumeration XML-backed models, projection/client Marble, and layered PL/SQL
5. Index strategically: Measure recurring access paths and deliver indexes through supported source
6. Respect concurrency metadata: Preserve and send projection ETags where the contract requires them
7. Avoid tight coupling: Make required component dependencies explicit and keep optional cross-component links genuinely optional
8. Design for upgrade readiness: Minimize schema changes; use projections for flexibility
9. Test comprehensively: Server validation, API contract, permissions, concurrency, integration, and data migration before production
10. Monitor performance: Use the supported service/database telemetry available for the operating model and tune measured access paths

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.

---

Further Reading

• IFS Cloud technical documentation
• IFS Developer Studio projection source reference
• IFS Community Forums
• Entity Relationship and Projection Configuration