Custom Commands in IFS Aurena: Adding Buttons That Actually Do Things

Introduction

If you've spent time in IFS Aurena, you know that out-of-the-box functionality is powerful—but rarely covers everything your business needs. That's where custom commands come in. Custom commands are the buttons and actions that transform Aurena pages from "display-only" interfaces into active business tools where users can execute custom logic, update records, and drive workflows.

The beauty of custom commands in IFS Aurena is that you have two equally valid paths to implement them:

1. Configuration Path — Quick, no-code button wiring via Page Designer
2. Developer Studio Path — Full control using client files and custom command definitions

This guide covers both approaches, complete with PL/SQL wiring, confirmation dialogs, parameter passing, and the gotchas that trip up newcomers.

---

Part 1: Understanding Custom Commands & Actions

Before you build, you need to understand the relationship between two core concepts:

Custom Actions: The Backend API

A Custom Action is a PL/SQL method you want to expose through the Aurena UI. It lives in the database (typically in your business logic packages) and is registered in a Projection Configuration.

Key characteristics:

• Simple parameters only (VARCHAR2, NUMBER, DATE)
• No return values (you can't get data back)
• Cannot use complex types (PL/SQL Records, BLOBs, CLOBs)
• Must be explicitly approved and published before use

Commands: The User-Facing Buttons

A Command is what users click. It's the glue between the page and the backend logic. Commands can:

• Execute Custom Actions (calling PL/SQL methods)
• Navigate between pages (with or without parameters)
• Navigate to external URLs
• Execute Quick Reports
• Open dialogs with confirmation logic

---

Part 2: The Configuration Path

For most functional consultants and admins, the Configuration path is the practical choice. It requires no development environment, no code deployment, and no rebuilding client files.

Step 1: Define the Custom Action

Navigate to Projection Configuration (or create a new projection):

1. Go to the relevant projection (or create one using the New Projection Configuration Assistant)
2. In the Add Actions step:
   • Action Name: Start with an uppercase letter. No spaces. Example: ApproveOrder
   • PL/SQL Method: Select from the list of available procedures in your logical units
   • LU Dependencies: Choose entities that need to refresh after the action runs (e.g., CustomerOrder, OrderStatus)
   • Action Approved: Toggle to approve the action
   • Action Published: Toggle to publish it

Example:

Action Name: ReleaseCustomerOrder
PL/SQL Method: CUSTOMER_ORDER_API.Release__
LU Dependencies: CustomerOrder, OrderStatistics

After saving, the action is registered in the projection and available for command mapping.

Step 2: Add the Command to a Page

Navigate to the Aurena Page where you want the button:

1. Click Aurena Page Designer (or the design icon in the page header)
2. Under the Active Page, find the Commandgroups section
3. Click the + icon next to Commandgroups
4. Select Execute Action (not Navigation Link)
5. Fill in:
   • Label: Text for the button (e.g., "Release Order")
   • Action: Select your Custom Action from the dropdown
   • Parameter Mappings: Map the action parameters to page/record attributes

Parameter Mapping Example: If your action needs OrderNo and CompanyId:

• OrderNo → Map to record attribute OrderNo
• CompanyId → Hardcode to a static value or pull from another field

Click the Edit icon next to "Parameter Mappings" to configure this.

Step 3: Deploy and Test

1. Submit the configuration
2. The command now appears as a button on your Aurena page
3. Users can click it directly—no page refresh required

---

Part 3: The Developer Studio Path

For developers who want full control, custom commands in Developer Studio offer:

• Conditional logic (enable/disable based on record state)
• Confirmation dialogs with custom messages
• Multi-step workflows
• Client-side validation before calling the backend

Step 1: Create or Edit the Client File

Client files live in your project's Client folder (typically under a component like FNDBAS). They define the page structure, fields, and commands.

Basic Command Structure:

COMMANDS

command ReleaseCommand for CustomerOrder {
  label = "Release";
  execute {
    call Release();
  }
}

Step 2: Add Confirmation Dialogs

Confirmation dialogs prevent accidental actions. The syntax is simple:

command ReleaseCommand for CustomerOrder {
  label = "Release";
  execute {
    confirm("Are you sure you want to release this order?") {
      when OK {
        call Release();
      }
      when CANCEL {
        exit;
      }
    }
  }
}

The confirm() function supports two outcomes: OK and CANCEL. The when blocks define what happens for each.

Step 3: Pass Parameters from the Page

If your PL/SQL method needs parameters, map them from the record context:

command ApproveAndNotifyCommand for CustomerOrder {
  label = "Approve & Notify";
  execute {
    confirm("Approve this order and notify the customer?") {
      when OK {
        call ApproveAndNotify(
          OrderNo = OrderNo,
          CustomerEmail = CustomerRef.Email,
          ApprovalDate = TODAY
        );
      }
      when CANCEL {
        exit;
      }
    }
  }
}

Here, OrderNo and CustomerEmail come from the current record context. TODAY is a built-in function.

Step 4: Conditional Enable/Disable

You can enable or disable commands based on record state:

command ReleaseCommand for CustomerOrder {
  label = "Release";
  enabled = (Objstate == "Planned");
  execute {
    confirm("Release this order?") {
      when OK {
        call Release();
      }
      when CANCEL {
        exit;
      }
    }
  }
}

If Objstate is not "Planned", the button will be greyed out.

Step 5: Add Commands to the Page Structure

In the page definition, reference the command:

page CustomerOrderDetails for CustomerOrder {

  // Page title
  title = "Customer Order Details";

  // Add command to the toolbar
  commandgroup {
    command ReleaseCommand;
    command ApproveAndNotifyCommand;
    command DeleteCommand;
  }

  // Fields for the detail form
  field OrderNo;
  field OrderDate;
  field CustomerRef;
  field Objstate;
  field TotalAmount;
}

Step 6: Deploy the Client File

1. In Developer Studio (Marble), generate the client file
2. Deploy it to your development database
3. Restart the Aurena server or reload the page in the browser
4. The commands now appear in the command toolbar

---

Part 4: Advanced Techniques

Passing Hidden Parameters

Sometimes you need to pass a parameter that isn't displayed as a field on the page:

In the Configuration path, you can add attributes to the page that aren't visible in the UI, then use them in parameter mappings.

In Developer Studio, pass them directly:

command CreateFollowUpOrder for CustomerOrder {
  label = "Create Follow-Up";
  execute {
    call CreateFollowUp(
      SourceOrderNo = OrderNo,
      CreatedBy = CURRENT_USER,
      CreatedDate = NOW
    );
  }
}

Using Dialogs Instead of Confirm

For more complex interactions, use dialog:

command SetDeliveryDateCommand for CustomerOrder {
  label = "Set Delivery Date";
  variable DeliveryDate;
  execute {
    dialog SelectDateDialog(OrderNo) into DeliveryDate {
      when OK {
        call SetDeliveryDate(DeliveryDate);
      }
      when CANCEL {
        exit;
      }
    }
  }
}

This assumes you've defined a SelectDateDialog in the same client file.

Navigation After Execution

Some workflows require navigating to another page after a command completes:

command ApproveAndNavigateCommand for CustomerOrder {
  label = "Approve & Go to Fulfillment";
  execute {
    confirm("Approve and move to fulfillment?") {
      when OK {
        call Approve();
        navigate to ApprovalSummary with parameters (
          OrderNo = OrderNo,
          Status = "Approved"
        );
      }
      when CANCEL {
        exit;
      }
    }
  }
}

---

Part 5: Common Pitfalls & Solutions

Pitfall 1: Parameter Not Mapping Correctly

Problem: You've added a field to the page, but the command still passes NULL.

Solution: In Parameter Mappings, ensure the attribute is correctly selected from the dropdown. For nested references (like CustomerRef.Email), make sure the reference is included in the page's projection.

Pitfall 2: Custom Action Requires Method Overload Selection

Problem: Your PL/SQL method exists but doesn't appear in the Custom Action LOV.

Solution: Ensure:

• The method uses simple parameter types (VARCHAR2, NUMBER, DATE)
• It's a procedure, not a function
• It's not in a _SVC, _CPI, or _RPI package

Pitfall 3: Button Is Enabled But Does Nothing When Clicked

Problem: You've added a command, but nothing happens.

Solution: Check:

• Is the PL/SQL method actually callable? (Permissions, grants)
• Have you deployed the projection configuration or client file?
• Is the Aurena server caching the old page? (Clear browser cache or restart server)

Pitfall 4: Confirmation Dialog Doesn't Appear

Problem: The action runs immediately without asking for confirmation.

Solution: The confirm() syntax requires explicit when OK and when CANCEL blocks. If one is missing, the dialog may not appear. Ensure your command definition is complete.

Pitfall 5: Migration from Apps 10 IEE Custom Menus

Problem: You have custom menu items from IEE that don't work in Aurena.

Solution: Aurena doesn't use custom menus. Rebuild them as Custom Actions + Commands following the steps above. The business logic (PL/SQL) can usually be reused; only the UI wiring changes.

---

Part 6: Configuration vs. Developer Studio: When to Use Each

Use Configuration Path If:

• You're a functional consultant without a development environment
• The command is simple (one action, no complex conditionals)
• You want faster time-to-value (no build/deploy cycle)
• You don't need client-side validation or complex dialogs
• Your action doesn't require conditional enable/disable

Use Developer Studio If:

• You have a development environment set up
• The command needs conditional logic or complex dialogs
• You want to build reusable custom pages
• You're migrating complex workflows from IEE
• You need version control and team collaboration

---

Part 7: Best Practices

1. Name Actions and Commands Clearly

Use action names that describe what they do:

• ✅ ReleaseCustomerOrder
• ❌ Action1

Use command labels that match your business process:

• ✅ "Release to Warehouse"
• ❌ "Execute"

2. Always Add Confirmation for Destructive Actions

Any action that modifies state should have a confirm() dialog:

command DeleteOrderCommand for CustomerOrder {
  label = "Delete Order";
  execute {
    confirm("Permanently delete this order? This cannot be undone.") {
      when OK {
        call Delete();
      }
      when CANCEL {
        exit;
      }
    }
  }
}

3. Validate Parameters Before Passing

In Developer Studio, validate inputs before calling the action:

command ApproveWithValidationCommand for CustomerOrder {
  label = "Approve";
  execute {
    if (Objstate != "Pending") {
      alert("Only pending orders can be approved.");
      exit;
    }
    confirm("Approve this order?") {
      when OK {
        call Approve();
      }
      when CANCEL {
        exit;
      }
    }
  }
}

4. Document Your Custom Actions

In the Projection Configuration, document what each action does in comments. In Developer Studio, use inline comments in the client file:

// Release the order and notify the warehouse
command ReleaseCommand for CustomerOrder {
  label = "Release to Warehouse";
  execute {
    confirm("Release this order to warehouse?") {
      when OK {
        call Release();
      }
      when CANCEL {
        exit;
      }
    }
  }
}

5. Test Parameter Mappings Thoroughly

When you add commands, test with different record states and parameter values. Ensure that hardcoded parameters and mapped attributes work as expected.

6. Plan for LU Dependencies

Choose your LU dependencies carefully. They tell Aurena which entities to refresh after the command runs. Too few, and stale data displays. Too many, and performance suffers.

Example: If your action updates both CustomerOrder and CustomerOrderLine, list both as dependencies.

---

Part 8: Real-World Example: Multi-Step Approval Workflow

Let's build a complete example: a Purchase Order approval workflow with confirmation and conditional logic.

Step 1: Create the Custom Actions

In Projection Configuration, add two actions:

Action 1:
  Name: ApprovePurchaseOrder
  Method: PURCHASE_ORDER_API.Approve__
  LU Dependencies: PurchaseOrder, PoStatus

Action 2:
  Name: RejectPurchaseOrder
  Method: PURCHASE_ORDER_API.Reject__
  Parameters: RejectReason
  LU Dependencies: PurchaseOrder, PoStatus

Step 2: Add Commands to the Page (Configuration Path)

In Page Designer, add two commands:

Command 1:

• Label: "Approve"
• Action: ApprovePurchaseOrder
• Parameter Mappings: (none needed)

Command 2:

• Label: "Reject"
• Action: RejectPurchaseOrder
• Parameter Mappings:
  • RejectReason = (hardcoded or from a field)

Step 3: Alternative - Developer Studio Version

command ApprovePOCommand for PurchaseOrder {
  label = "Approve";
  enabled = (Objstate == "Submitted");
  execute {
    confirm("Approve this PO? The vendor will be notified.") {
      when OK {
        call Approve();
      }
      when CANCEL {
        exit;
      }
    }
  }
}

command RejectPOCommand for PurchaseOrder {
  label = "Reject & Send Back";
  enabled = (Objstate == "Submitted");
  variable RejectionReason = "";
  execute {
    // You could prompt for a reason here
    confirm("Reject this PO? The vendor will be notified.") {
      when OK {
        call Reject(RejectionReason = "Rejected by approver");
      }
      when CANCEL {
        exit;
      }
    }
  }
}

Step 4: Test

1. Create a test PO in "Submitted" state
2. Navigate to the PO detail page
3. The "Approve" and "Reject" buttons appear (enabled only if state is "Submitted")
4. Click "Approve", confirm the dialog, and verify the PO state changes

---

Part 9: Troubleshooting Checklist

---

Conclusion

Custom commands are the bridge between Aurena's UI and your business logic. Whether you choose the Configuration path (faster, simpler) or Developer Studio (more control, more power), you now have the tools to:

• Expose PL/SQL methods as user-facing buttons
• Add confirmation dialogs to prevent accidents
• Pass parameters from pages to backend logic
• Build conditional workflows based on record state
• Navigate between pages after actions complete

Start simple—add a single action and command to test your setup. Once you're comfortable with the basics, layer in confirmation dialogs, conditional logic, and multi-step workflows.

Your users will love having buttons that actually do things.

---

Further Reading

• IFS Custom Actions & Commands Documentation
• Command Component Reference
• Custom Action Configuration Guide
• IFS Community: Search for "custom commands Aurena" for real-world examples