If you’ve ever tried to reference a User Exception across modules in OutSystems, you’ve likely hit a frustrating wall: OutSystems does not allow User Exceptions to be public. This means you can’t directly catch or handle a custom exception type thrown from a core or producer module in your consumer modules. For microservices and modular architectures, this limitation can be a real pain.
But there’s good news—there’s a reliable workaround that lets you typify and handle exceptions in a robust, scalable way.
The Workaround: Typifying User Exceptions
Here’s how you can implement a pattern that lets you “pass” exception types across module boundaries, even though User Exceptions themselves can’t be public.
1. Create a Static Entity for Exception Types
Define a Static Entity to represent your different exception types. For example:
- EmailNotVerified
- MaintenanceMode
- ApiError
- …add as many as your application needs.
This static entity will act as your reference for exception types throughout your modules.
2. Build a Structure for Exception Details
Create a Structure to hold:
- The Exception Type ID (from your static entity)
- An Error Message
This structure will be used to pass exception information between modules.
3. Create the Serialization and Deserialization actions
Create the Serialization action:
- Accepts the Exception Type ID and Error Message as input parameters.
- Serialize these into a JSON string (since OutSystems User Exceptions only accept a text message).
This action will be used to pass exception details when raising User Exceptions.
Create the Deserialization action:
- Accepts the exception message (the JSON string) as input.
- Deserialize it back into your exception structure.
- Make sure to add an Exception Handler to prevent runtime error when passing invalid JSON text.
4. Implementing the Pattern
- In your UI, trigger exceptions (e.g., via button clicks) that call the serialize action with different exception types and messages.
- In your global exception handler (e.g., under the Common flow’s All Exceptions handler), call your deserialization action and use a Switch node to do the necessary logic per Exception Types:
- For MaintenanceMode, redirect to a maintenance screen.
- For EmailNotVerified, show a specific error message.
- For ApiError or unknown types, show a generic error.
Why This Works
- Modular: You can define and handle as many exception types as you need, without leaking implementation details across modules.
- Maintainable: All exception logic is centralized and easy to extend.
- Scalable: Works for both microservice and monolithic OutSystems architectures.
Example Use Case
Suppose you have three buttons in your UI:
- Maintenance Mode: Triggers a MaintenanceMode exception, redirecting users to a maintenance screen.
- Email Not Verified: Triggers an EmailNotVerified exception, showing a tailored error message.
- API Error: Triggers an ApiError, displaying a generic error message.
Each button calls the serialize action with different parameters, and the exception handler routes the flow accordingly.
Key Takeaways
- OutSystems does not support public User Exceptions, but you can typify exceptions using static entities and structures.
- Serialize exception details into the exception message and deserialize them in your handler for flexible, type-safe error handling.
- This approach keeps your exception handling clean, robust, and maintainable—even in large, modular OutSystems applications.
