Building a Custom IFS Aurena Page from Zero

Building a custom page in IFS Aurena from scratch can seem daunting at first. But once you understand the architecture—entity models, projections, client files, and the declarative Marble language—you'll find it's a logical, well-structured process. This guide walks you through every step, from setting up your development environment to deploying a fully functional page with navigation and command buttons.

The Architecture at a Glance

Before diving into code, let's map out what we're building:

1. Entity Model – The database structure and business logic layer (PL/SQL)
2. Projection – An OData endpoint that exposes your entity as a consumable API
3. Client File – Declarative Marble UI definitions (pages, lists, groups, commands)
4. Navigator Entry – Navigation menu integration to make your page discoverable
5. Deployment – Grant permissions and test the whole pipeline

Each layer builds on the previous one, and each is defined in Developer Studio.

Prerequisites

Before you start, you'll need:

• Developer Studio – IFS's IDE for Aurena development (installed via Setup Dev Tools)
• Access to Subversion – For version control and component management
• A development database – Typically a copy of production for testing
• Marble language knowledge – Basic syntax and structure
• PL/SQL skills – For entity definitions and backend logic
• A configured build home – Points to shared component libraries

If you don't have Developer Studio set up, go to your IFS environment's Tools menu and click Setup Dev Tools, then follow the installation wizard.

Step 1: Setting Up Your Development Environment

Create a Project

Open Developer Studio and create a new IFS R&D Core Project:

1. Click File → New Project (or right-click in the Projects tab)
2. Select IFS R&D Core Project
3. Enter a project name (e.g., C:\SVN\Aurena\workspace\fndbas)
4. Set the Build Home to point to your shared component library (e.g., \\server\UXX_WAVE_Dev\Build\Home)
5. Check Use Build Home Target Version
6. Add your development database connection (e.g., jdbc:oracle:thin:@//server:1521/database)
7. Click Finish

The build home is critical—it allows you to reference existing entities and components without importing the entire library into your local project.

Verify Component Access

Once your project is created, expand the fndbas component in the Projects panel. You'll see the /Client folder where projection and client files live.

Step 2: Creating the Projection

What Is a Projection?

A projection is an OData service definition that exposes your entity to the Aurena UI layer. It's the bridge between your database and your pages. Every custom page needs a corresponding projection.

Create the Projection File

1. Right-click the fndbas component
2. Select New → Projection Model
3. Name it (e.g., InventoryMovement)
4. Click Finish

A new file InventoryMovement.projection is created in /Client.

Define Entity Sets

Open your projection file and add an entityset. This is the data source that will feed your pages:

Key concepts:

• @DynamicComponentDependency – Reference an external component. Avoids importing the entire component locally.
• entityset – Names your OData endpoint and links it to a database entity.
• MAIN ENTRY POINTS – The primary data sources for your projection.
• ENTITY DETAILS – Advanced entity configurations (added later if needed).

Grant Permissions

Deploy your projection, then grant permissions via Developer Studio's SQL command:

Right-click Database → Execute Command and paste this script.

Test the Projection

Verify the OData endpoint works:

https://<server>:<port>/main/ifsapplications/projection/v1/InventoryMovement.svc/InventoryMovements?$top=10

You should see XML data from your entityset. If it works, your projection is live.

Step 3: Building the Client File

Create the Client

1. Right-click fndbas again
2. Select New → Client Model
3. Name it to match your projection (e.g., InventoryMovement.client)
4. Click Finish

A new file InventoryMovement.client is created with four main regions:

Define Visual Components (Lists & Groups)

Start with a list that displays your data:

Field ordering matters – Fields appear in the order listed. Use fieldranking to prioritize critical fields on mobile views:

Now create a detail group for a single record view:

Create Pages

Pages tie together your visual components with data:

Page types:

• List Page – Shows multiple records in a table (ideal for grids, dashboards)
• Group Page – Single record view with detailed fields (ideal for editing)
• Card View – Compact record preview
• Assistant – Step-by-step wizard (multi-page flow)

Add Commands (Buttons)

Commands are interactive buttons that trigger actions. Define them in the COMMANDS section:

Command types:

• action – Create, Update, Delete operations
• function – Call a backend PL/SQL function
• navigate – Go to another page (with optional parameters)
• dialog – Open a modal dialog
• confirm – Ask for user confirmation before proceeding

Enablement rules: Control when buttons appear using conditional logic:

This is state-based command enablement – a powerful pattern for enforcing business rules.

Wire Commands to Pages

Add commands to your pages:

Step 4: Adding Navigator Entries

Navigator entries make your pages discoverable in the Aurena sidebar menu.

Key concepts:

• toplevel – Creates a top-level folder in the navigator (visible at the root level)
• at index – Controls menu ordering (lower numbers appear first)
• label – The text shown in the menu
• entry (sub-entries) – Nested items under a parent
• page – Links the entry to an actual page

You can also create entries under existing IFS modules without using toplevel:

Step 5: Advanced Features

Understanding Marble Syntax in Depth

Marble is the declarative language at the heart of Aurena development. Unlike traditional programming languages, Marble focuses on declaring what your UI should be, not how to build it. Understanding its syntax deeply will help you avoid common mistakes.

Declarations vs. Overrides

When you define a list for the first time, you're creating it:

Later, if you need to customize that list (perhaps in a different page context), you override it:

Overrides are powerful—they let you extend components without redefining them from scratch.

Using Annotations Effectively

Annotations modify component behavior. The most common is @DynamicComponentDependency, but there are others:

• @Immutable – Makes fields read-only
• @Hidden – Hides a field from display
• @Required – Marks a field as mandatory
• @Label – Overrides field labels
• @Tooltip – Adds hover text

Example:

Expression Language in Marble

Marble supports condition expressions for enablement, visibility, and default values:

Common operators:

• = – Equality
• != – Inequality
• >, <, >=, <= – Comparisons
• and, or – Logical operators
• not() – Negation
• null, empty – Null/empty checks

Dialogs for User Input

Create modal dialogs for data entry or confirmation:

Link it to a command:

Selectors and Filters

Use selectors for multi-select filtering:

Groups vs. Lists: When to Use Each

It's easy to confuse groups and lists in Aurena. Here's when to use each:

Lists are for displaying and editing multiple records:

Groups are for displaying and editing a single record at a time:

You can also embed groups within lists to show related data:

Responsive Design in Aurena

Aurena automatically adapts to different screen sizes, but you need to guide it. Use fieldranking to tell Aurena which fields are critical:

When the screen shrinks, Aurena hides fields from the end of the list first. The ranked fields stay visible, ensuring critical data is never hidden.

On mobile, a ranked list might show only 2-3 columns. On desktop, all fields display. On tablet, something in between. Aurena handles the breakpoints automatically.

Integrating with IFS Backend Functions

OneofAurena's superpowers is seamless integration with your existing PL/SQL business logic. Commands can call backend functions without writing a single line of JavaScript.

Define a command that calls a function:

Your backend can accept parameters and return values:

The function call passes the current record's data automatically. The backend function can:

• Perform calculations
• Update related records
• Validate business rules
• Generate attachments or reports
• Trigger workflows

All without writing custom JavaScript or HTTP handlers.

Charts and Visualizations

Add charts to dashboard pages:

Conditional Formatting

Show/hide or enable/disable fields based on conditions:

Step 6: Performance Optimization

Minimizing OData Calls

Each field you display in a list triggers an OData query. Too many fields = slow pages. Follow these best practices:

1. Only show necessary fields – Don't include every attribute in your entity
2. Use fieldranking – Prioritize critical fields; optional ones load on-demand
3. Avoid nested lists – Each nested list is another OData call
4. Cache data when possible – Use projection caching for read-heavy pages

Query Optimization

In your projection, you can optimize the underlying OData queries:

Step 7: Deployment and Testing

Deploy the Client File

1. Right-click your client file in Developer Studio
2. Select Deploy
3. Wait for the "Deployment successful" message

Test Your Page in Aurena

Open Aurena (IFS Cloud Web) and navigate to your page:

https://<server>:<port>/main/ifsapplications/web/page/InventoryMovement/InventoryOverview

You should see:

• Your list populated with data from the projection
• Your commands as buttons in the toolbar
• Your navigator entry in the sidebar
• Full CRUD functionality (Create, Read, Update, Delete) if enabled

Debug Issues

Enable the Aurena debug console:

1. Log in to Aurena
2. Click your profile icon (top right)
3. Select Debug: Enable Debug Console
4. Go to the Page Info tab to verify the projection name
5. Check the Network tab for API errors

Common issues:

• "Projection not found" – Check projection name spelling and ensure it's deployed
• "OData query failed" – Verify permissions with the grant script
• "Fields not showing" – Confirm fields exist in your entity and are listed in the client file
• "Commands disabled" – Review your enabled conditions and entity state values

Troubleshooting Common Issues

Issue: "Projection Not Found" Error

Cause: The projection name in your client file doesn't match the deployed projection.

Solution:

1. Verify the projection name is spelled correctly (case-sensitive)
2. Ensure the projection is deployed
3. Check that the projection exists in your build home or local project
4. Grant permissions to the projection

Issue: "OData Query Failed" Error

Cause: Missing permissions on the projection or entity.

Solution:

1. Run the grant script in Developer Studio
2. Verify the entity exists in your database
3. Check entity permissions in SQL

Issue: Fields Not Showing in List

Cause: Field names don't match entity attributes, or they're hidden/disabled.

Solution:

1. Verify field names against the actual entity
2. Check for @Hidden annotations
3. Review enabled/visible conditions
4. Ensure the field is included in your entityset select list

Issue: Commands Always Disabled

Cause: Incorrect enablement condition or object state mismatch.

Solution:

1. Remove the enabled condition to test
2. Verify the state field and its possible values
3. Use debug console to inspect the record's state

Complete Example: Inventory Movement Page

Here's a full, production-ready client file example to tie it all together:

Key Takeaways

1. Projections are essential – Every page needs an OData endpoint. Think of it as the contract between your database and your UI.

2. Client files are declarative – You describe the UI, not code it. Aurena handles responsivity, accessibility, and interactions.

3. Commands drive workflows – State-based command enablement enforces business logic without writing custom validation code.

4. Navigator entries make pages discoverable – Users won't find your page unless it's in the menu. Navigator structure matters.

5. Field ranking improves mobile UX – Explicitly prioritize critical fields for responsive views.

6. Dynamic dependencies avoid bloat – Use @DynamicComponentDependency to reference external components without importing them.

7. Test early and often – Use the OData URL to verify data, the page URL to verify UI, and the debug console to troubleshoot.

8. Permissions are non-negotiable – Without the grant script, even perfect code won't work.

Next Steps

From here, you can:

• Add more entities – Create projections and clients for related data
• Build assistants – Multi-step wizards for complex processes
• Add charts and dashboards – Visualize KPIs with built-in components
• Integrate with other pages – Navigate between custom and standard IFS pages
• Customize styling – Override default look-and-feel with CSS customizations
• Deploy to production – Use layered development to push changes safely

Building custom Aurena pages is as much art as science. The Marble language keeps things clean and maintainable, but understanding your entity model and how data flows through projections to the UI is what separates good pages from great ones.

Deployment Checklist

Before going live, verify:

• Projection created and deployed
• Projection permissions granted
• OData endpoint tested (returns data)
• Client file created and deployed
• All field names match entity attributes
• Navigator entries created and tested
• Commands wired to functions/actions
• Enablement conditions tested
• Page accessible via direct URL
• Page visible in navigator
• Mobile responsive (check on tablet/phone)
• Performance acceptable (lists load in <2 seconds)
• Error handling in place (what if no data exists?)
• Tested with different user roles/permissions
• Documentation updated for end-users

Real-World Best Practices

1. Use consistent naming conventions – InventoryMovement for entity, projection, and client files
2. Document your projections – Add clear descriptions in the projection file
3. Version control everything – Use SVN or Git; Aurena development is code
4. Test incrementally – Don't build the entire page before testing
5. Keep projections focused – Don't expose unnecessary data via OData
6. Use dynamic dependencies – Avoid bloating your local project
7. Monitor performance – Use browser dev tools to check network requests
8. Follow IFS naming standards – Adhere to your organization's conventions
9. Reuse components – Build visual components once, use them many times
10. Document state transitions – Make it clear to users what states and transitions are allowed

Learning Resources

• IFS Developer Documentation – https://docs.ifs.com/techdocs
• Marble Language Reference – Component reference docs
• IFS Community Forums – Real-world questions and answers
• Sample Pages – Explore existing IFS pages to understand patterns
• Developer Studio Help – Built-in documentation in the IDE

Conclusion

Building custom Aurena pages is a blend of declarative thinking, database design, and UX sensibility. You don't need to be a JavaScript expert—Aurena handles interactivity for you. Instead, focus on:

• Clean entity models
• Well-designed projections
• Thoughtful field selection
• Intuitive navigation
• Smart command enablement

Start small. Build a list page. Add a detail page. Introduce commands. Test at each step. Before long, you'll have built a sophisticated, responsive, production-grade page that IFS users love.

Happy building! 🚀