IFS Marble Language: A Field Guide

Marble. If you've been handed an IFS Cloud Aurena customization and stared at a .marble file wondering what you're looking at, you're not alone. The IFS documentation scatters Marble syntax across dozens of pages, and the Developer Studio's hints aren't always complete. This guide brings it all together—practical patterns, real syntax, and the gotchas that catch every new developer.

What Is Marble?

Marble is a Domain-Specific Language (DSL) that sits at the heart of IFS Aurena's presentation tier. It's not SQL, not PL/SQL, not JavaScript—it's purpose-built for describing UI components, projections, entities, fields, and the business logic that connects them.

Why Marble exists: IFS Cloud separates presentation (client) from business logic (server). Marble bridges that gap declaratively. You describe what UI you need, what data it exposes, and what it should do—then the framework handles the plumbing.

Where you write Marble:

• Projection files (.projection) — Define how an entity appears in the UI, what fields show, and what actions/functions are available
• Client files (.client) — Define client-side views, controls, pages, and computed fields
• Entity definitions — Attribute metadata, virtual fields, and constraint rules

This guide focuses on projection and entity-level Marble, where 90% of new developers spend their time.

---

Part 1: Entity Definitions and Attributes

Entities in Marble map 1:1 to database tables (usually), but they're not just database schemas. They define the logical structure of your domain model.

Basic Entity Syntax

Every entity needs:

• A key — uniquely identifies a record. Can be compound (multiple fields)
• Attributes — named fields with data types
• A unique name in camelCase (converted to UPPER_CASE in the database)

Attribute Types

Attribute Flags and Modifiers

Flags control how the database table is generated and how the application validates the data:

Common flags:

• Key — Part of the primary key
• MandatoryEnter — NOT NULL constraint; user must provide a value
• ParentKey — Foreign key to parent entity (enforces referential integrity)
• SearchKey — Indexed and searchable in queries
• AllowNull — Explicitly allows NULL (opposite of MandatoryEnter)

Important: A field with no flag defaults to allowing NULL unless marked MandatoryEnter.

Fetch Attributes: Virtual Data

Not all data lives in your table. Fetch attributes pull data from the database at runtime—great for denormalization and avoiding joins in the UI.

Fetch rules:

• The SQL or function call is executed every time the entity is queried
• Parameters use colon syntax (:FieldName)
• You can reference any field in the current entity
• Fetch operations are read-only — no INSERT/UPDATE/DELETE
• Performance tip: Use fetch sparingly; prefer explicit relationships when possible

Virtual Attributes (Computed on the Fly)

Virtual attributes live only in memory—they're not stored in the database, but computed from other fields.

Virtual attribute syntax:

• Keyword: virtual
• Expression uses #{...} for numeric calculations or ${...} for string interpolation
• Computed every time the entity is retrieved; always up-to-date

---

Part 2: Projections — The UI Layer

A projection is Marble's way of saying "here's what the UI sees." It defines:

• Which entities and their fields appear
• What actions the user can perform
• What functions provide data

Projection File Structure

Breaking it down:

• metadata — UI labels and descriptions
• entity block — Defines the primary entity and its attributes
• exec — The PL/SQL package that implements the entity logic
• action — Performs an operation that changes data
• function — Queries data without changing anything

The exec Clause

Every entity in a projection needs an exec clause pointing to a PL/SQL package:

The framework expects this package to contain procedures like:

• New__(in_record IN WorkOrderTab%ROWTYPE) — Insert
• Modify__(in_record IN WorkOrderTab%ROWTYPE) — Update
• Remove__(in_record IN WorkOrderTab%ROWTYPE) — Delete

If your entity doesn't have a corresponding PL/SQL package, you'll get runtime errors.

---

Part 3: Actions vs. Functions

The difference is deceptively simple, but it's one of the most common sources of confusion:

Action Example

The .plsvc file implements this:

Function Example

The .plsvc file:

Key difference: The action changes the database; the function only reads.

---

Part 4: Attributes in Projections

Projection attributes map to database columns and define how they behave in the UI.

Basic Attribute Definition

Computed Fields (Client-Side Calculations)

Computed fields exist only in the UI layer, calculated on the client:

Computed field expressions:

• #{...} — Numeric calculation
• ${...} — String substitution
• .count() — Aggregate count from related data
• Updates automatically when source fields change

---

Part 5: References and Relationships

References link entities together, enabling the UI to navigate and display related data.

Defining References

Reference binding: The bind clause tells the framework which fields to use for the join.

---

Part 6: The Common Gotchas

Gotcha #1: Forgetting the exec Clause

This will compile, but when you try to create/update/delete an Order in the UI, the runtime will throw an error: "Package ORDER_API not found." You must always specify exec = "Order_API" or equivalent.

Fix: Always add exec = "PackageName_API" to every entity in a projection.

Gotcha #2: Mixing Fetch with Mandatory

If the fetch query returns NULL (because the subquery finds nothing), the mandatory validation will fail even though the field was populated by Marble itself. The mandatory flag applies after the fetch.

Fix: Use mandatory = "false" on fetch attributes, or ensure your fetch query always returns a value (use COALESCE).

Gotcha #3: Attribute Naming and Capitalization

Marble converts camelCase to UPPER_CASE for database columns. OrderNo → ORDER_NO. If your database column is actually named ORDER_NUMBER, the binding will fail.

Fix: Always use camelCase in Marble. Verify the column names in your database match the generated names.

Gotcha #4: Virtual Attributes in Grouping/Sorting

You cannot group by, sort by, or filter on virtual attributes. They're computed after the data is fetched. If you need to sort by calculated values, move the logic to a fetch attribute.

Fix: Use a fetch attribute (computed in the database) if you need sorting/grouping. Virtual attributes are display-only.

Gotcha #5: Action Parameters and Binding

The .plsvc file must have exactly matching parameter names, including capitalization:

Actually, the parameter names don't have to match character-for-character (Marble handles mapping), but the count and order must be exact. If the Marble definition has 2 parameters, the PL/SQL must have 2.

Fix: Use in_parameter_name convention in PL/SQL and trust the framework's mapping.

Gotcha #6: Forgetting the Projection File Wraps Execution

Functions and actions defined in one projection are not automatically visible to other projections.

Fix: Prefix external references with the projection name: ProjectionName.FunctionName().

Gotcha #7: Fetch Attributes on Read-Only Entities

This works fine—fetch attributes can be used on read-only entities. But if you add a write operation (action) to a read-only entity, the framework gets confused.

Fix: Don't mix read-only flags with modifiable actions. Use separate projections for read-only lookups and writable entities.

Gotcha #8: Computed Field Dependencies

Computed fields can reference base attributes, not other computed fields.

Fix: Expand the expression:

---

Part 7: Validation and Constraints

Validations in Marble ensure data integrity at the business logic layer.

Attribute-Level Validation

Custom Validation Rules

For complex validations, define rules in the .plsvc file and reference them:

The PL/SQL procedure:

---

Part 8: Best Practices and Performance Tips

1. Prefer References Over Fetch Attributes

Instead of:

Use:

References are optimized by the framework; fetch attributes hit the database every time.

2. Index Your Search Keys

3. Use Computed Fields for Display Logic Only

Computed fields are client-side only. Don't rely on them for business logic or persistence.

4. Document Your Fetch Attributes

5. Keep Actions Granular

6. Validate Early in Actions

In the .plsvc file, validate first before making changes:

---

Part 9: Debugging Marble Issues

Issue: "Attribute Not Found"

Error: Attribute 'CustomerNo' not found in entity

Check:

1. Spelling and capitalization: CustomerNo vs customerNo
2. Is the attribute defined in the entity block?
3. Is the binding correct in the exec clause?

Issue: "Function Not Found"

Error: Function 'GetCustomerOrders' not found

Check:

1. Is the function defined in the projection?
2. Is the .plsvc file compiled and deployed?
3. Are you prefixing with the projection name if calling from another projection?

Issue: Fetch Attribute Returning NULL

Returns NULL even when a record exists.

Check:

1. Does the subquery reference the correct table/column?
2. Are the bind parameters (:ID) available in the current context?
3. Use COALESCE() to provide a default if NULL is acceptable

---

Quick Reference: Marble Syntax

Entity Definition

Projection

Computed Field

---

Conclusion

Marble is powerful once you understand its conventions. The key takeaways:

1. Entities are logical models, not just database schemas
2. Projections are UI contracts — they define what the UI sees and can do
3. Actions modify, functions query — never mix them up
4. Fetch attributes are powerful but use them sparingly — prefer references
5. Validate early, validate often — push validation to the business logic layer (PL/SQL)
6. Name everything carefully — camelCase, consistent parameter counts, exact spellings
7. Test your bindings — the framework can't tell you if OrderNo is misspelled; it'll fail at runtime

When you're debugging a Marble issue, nine times out of ten it's one of the common gotchas: missing exec, mismatched parameter names, or a fetch attribute expecting data that doesn't exist.

Read the official IFS Aurena development documentation—especially the sections on Client Controls and Projection Controls—as your reference. This guide gives you the patterns and gotchas; the docs give you the complete syntax.

Happy projecting.