Writing Your First IFS Cloud Projection from Scratch

Projections are the bridge between IFS Cloud's powerful back-end logic and the modern Aurena user interface. They expose business entities as RESTful web services, making your data accessible, queryable, and interactive. In this guide, we'll walk through creating your first projection from the ground up—from modeling an entity in Developer Studio to deploying it in a dev environment.

Understanding IFS Projections

Before we dive into code, let's clarify what a projection does and where it fits in the IFS architecture.

What is a Projection?

A projection is a model that exposes functional business logic from IFS Cloud as a RESTful web service. It acts as an abstraction layer between the database (where your core entities live) and the client UI. The projection:

• Shields the client from direct database access
• Enriches the data with runtime logic and calculated fields
• Enforces business rules at the service layer
• Defines entry points via entitysets that clients consume
• Optionally includes PL/SQL logic for server-side operations

Think of it as a carefully curated view of your entity that includes only what the UI needs, plus any derived or computed fields.

The Layered Architecture

IFS Cloud uses a Layered Application Architecture (LAA) to keep customizations separate from the core product:

• Core Layer – IFS-provided standard functionality
• Extension (Ext) Layer – For extensions and enhancements
• Customization (Cust) Layer – For customer-specific modifications

When you write your own projection, you typically work in the Cust or Ext layer. This ensures that future IFS upgrades won't overwrite your work, and your changes are cleanly isolated.

Project Structure: File Types and Dependencies

IFS Aurena development involves three interconnected model file types:

1. Projection File (.projection)

The projection file defines the data structure and operations. It contains:

• Entity definitions – Which database entities to expose
• Entitysets – The REST endpoints available to clients
• References – Related entities that can be fetched
• Arrays – Collections of child records
• Actions & Functions – Operations the client can invoke
• Virtuals – Computed fields
• Enumerations – Domain value lists

2. PL/SQL Service File (.plsvc)

The .plsvc file contains the actual PL/SQL implementations:

• Custom action logic
• Function implementations
• Method overrides
• Server-side validation

It's generated alongside the .projection file but contains the business logic.

3. Client File (.client)

The client file defines the UI structure (pages, lists, dialogs). For this guide, we'll focus on projections, but the client depends on the projection for its data source.

Dependencies

When you commit a projection:

1. The projection depends on entities – You must reference existing database entities
2. If entities have enumerations, the projection depends on those
3. The client depends on the projection – The UI binds to projection data
4. During build, the code generator traverses these dependencies to validate everything is in place

Step 1: Understand Your Entity Model

Before writing the projection, you need to know your underlying entity. In this example, we'll create a projection for a hypothetical EmployeeBonus entity.

Typical Entity Structure

An entity in IFS Cloud has:

• Primary Keys – Unique identifiers (often composite)
• Attributes – Data fields with types
• References – Links to parent entities
• Derived Values – Calculated or fetched fields

For our EmployeeBonus example:

Step 2: Create the Projection File in Developer Studio

Open IFS Developer Studio and follow these steps:

Create a New Projection

1. Right-click on your component folder (e.g., FNDHCM for Human Capital Management)
2. New > Projection
3. Name: EmployeeBonus (descriptive, globally unique)
4. Layer: If this is a customization, set to Cust; for new core development, use Core
5. Component: Select the appropriate component (e.g., FNDHCM)
6. Description: "Projection for managing employee bonuses"

Set the Category and Dependency

Step 3: Write the Projection Marble Code

Now, let's build out the projection structure. Here's a complete example:

Understanding Entitysets

An entityset is the REST endpoint exposed by your projection. It maps to a specific entity and defines how it's queried:

The @DynamicComponentDependency annotation tells IFS to dynamically load the entity at runtime. This is particularly useful when you're referencing entities from different components, allowing your projection to work across the platform.

Attribute Types and Annotations

Marble supports several attribute types and modifiers:

Key modifiers:

• is key – Marks as primary key (required)
• readOnly – Client cannot modify
• mandatory – Must be provided when creating
• label "Display Name" – Human-readable label

Key Marble Syntax Explained

@DynamicComponentDependency – Declares runtime dependencies, allowing the projection to use dynamic entitysets.

entity – Defines the main data structure exposed by this projection.

attribute – A field from the underlying database entity or a computed value.

reference – A link to another entity. This creates a relationship that can be navigated from the client.

array – A collection of child records (similar to a one-to-many relationship).

virtual – A computed attribute calculated at runtime; not stored directly.

action – A server-side operation the client can invoke (like "ApproveBonus").

function – A callable operation that returns a value.

enumeration – A fixed set of allowed values (Draft, Approved, Paid).

structure – A complex data type returned by functions, not a main entity.

Step 4: Using @Override for Customizations

When you're working in the Cust layer and customizing an existing projection, you use @Override to modify only the parts you're changing.

Example: Adding a Field to an Existing Projection

Key Points:

• Only include the attributes/actions you're adding or modifying
• Use @Override on the entity itself
• Use @Override on individual attributes or methods you're changing
• The projection engine merges your Cust layer with the Core during code generation
• Never modify Core-layer files directly

Step 5: Working with References and Arrays

Projections aren't isolated—they often reference other entities. Understanding how to properly define and use references is critical.

One-to-One References

When a client requests an EmployeeBonus, they can expand the EmployeeRef to get the full Employee record:

GET /EmployeeBonuses(BonusId='B123')?$expand=EmployeeRef

This returns the bonus plus all Employee attributes in one response.

One-to-Many Arrays

Arrays represent child collections:

Now when you query an Employee, you can include their bonuses:

GET /Employees(EmployeeId='E001')?$expand=BonusesArray

Lazy Loading vs. Eager Loading

By default, references and arrays use lazy loading – they're not included unless explicitly requested via $expand. This improves performance for large datasets.

For frequently-needed data, you can use prefetch (older syntax) or $expand (modern OData):

Step 6: Define Entity Keys and Search Predicates

Entity keys are critical for REST operations. They uniquely identify records and form the URL path.

Simple vs. Composite Keys

Simple Key (one attribute):

Composite Key (multiple attributes):

When composite, the URL would look like:

/EmployeeBonuses(EmployeeId='E001',BonusYear=2025)

Search Predicates

You can define how records are filtered:

Step 6: Writing the PL/SQL Service File (.plsvc)

When you need custom logic for actions or functions, create a .plsvc file with the same name:

EmployeeBonus.plsvc:

Structure of .plsvc Files

• Package declaration – Matches your projection name
• Helper functions – Reusable validation and business logic
• Action procedures – Implement the actions you defined in Marble
• Functions – Implement the functions you defined
• Error handling – Use raise_application_error for validation failures
• Transactions – COMMIT on success, ROLLBACK on failure

Step 7: Code Generation and Compilation

Build and Generate

1. Save your projection file (.projection)
2. Save your service file (.plsvc)
3. In Developer Studio: Right-click your component > Build or Generate Code

The build process creates:

• EmployeeBonus.svc – Generated database package
• EMPLOYEEBONUS_SVC – PL/SQL package in the database
• Metadata files for Aurena

Monitor the Build Log

Check the Build Log or look in your build home at:

_ant_generate_db.log

Common issues:

• Entity not found – Check the referenced entity exists
• Syntax errors – Verify Marble syntax (matching brackets, semicolons)
• Package compile errors – Check .plsvc file for PL/SQL issues

Step 8: Deploy to Your Dev Database

Once your build is successful, the code must reach your development database.

Deployment Steps

1. Package the component – Include your .projection and .plsvc files
2. Add to your delivery – In IFS Deployment Manager, select your component
3. Deploy to dev – Execute the installation script on your dev environment

Verify Deployment

After deployment, check the database:

Step 9: Surfacing the Projection in Aurena

Now that your projection is live in the database, the final step is creating a Client file to expose it in Aurena.

Create a Client File

EmployeeBonus.client:

Pages and Navigation

• The page contains all UI elements for a business process
• Selectors let users choose a record
• Groups display detailed information
• Commands trigger projection actions
• Fields bind to projection attributes

The client file automatically finds your projection via its name and component, and generates the Aurena UI.

Step 10: Testing and Validation

Test via Aurena UI

1. Log into your Aurena environment
2. Navigate to the page you created (it'll appear in the HumanResources category)
3. Verify you can:
   • List bonuses
   • View details
   • Invoke the Approve action
   • See calculated fields update

Test via REST API

You can also test directly via the OData endpoint:

Best Practices and Key Takeaways

1. Keep Projections Lean

Don't expose every attribute of an entity. Include only what the UI needs. This improves performance and security.

2. Use References Wisely

References are powerful but can cause performance issues if overused. Prefer explicit selection over automatic fetching.

3. Separate Core and Customization

Always work in the Cust layer when possible. This keeps your upgrades clean and maintainable.

4. Test Early and Often

Generate and build frequently during development. Catch syntax errors before they accumulate.

5. Document Your Marble

Add descriptions and comments:

6. Validate in PL/SQL

Push business rules to the service layer. Use raise_application_error for validation failures, ensuring consistency across all clients.

7. Version and Track Changes

Use clear naming and comments in your projection files. When you create a new version, increment version numbers or add timestamps.

Conclusion

Creating a projection is the gateway to modern IFS Cloud development. By following this step-by-step guide, you've learned how to:

1. Model an entity in IFS terminology
2. Write Marble syntax for projection definitions
3. Use @Override for customizations in the Cust layer
4. Implement business logic in .plsvc PL/SQL files
5. Generate and build your projection
6. Deploy to dev and test in Aurena

Projections are the bridge between database and UI. Master them, and you unlock the full power of IFS Cloud customization. The patterns you've learned here—entity modeling, layered architecture, action and function definitions—apply to every projection you'll create.

Now it's your turn. Start with a simple entity, build your projection, and watch it come to life in Aurena. Happy coding!

---

Further Reading

• IFS Community: Marble Syntax Documentation
• IFS Docs: Aurena Component Reference
• IFS Docs: Customization Best Practices
• IFS Developer Studio: Built-in code hints and validation