OutSystems: Exception Handling Standards
Why a good Exception handling matters? Because bad, misleading error messages or invisible errors aren’t doing any good to anyone. Users are misled, maintenance guys don’t know where to look. You can see the big picture.
Exceptions vs Errors
There are several dissertations over the internet about this issue. This is not the focus of this article, but one of the most interesting things I’ve read is that “Errors are exceptions that are not up to the programmer to resolve. In fact it’s a bad idea for a programmer to handle this task.”
Things like outOfMemory or StackOverflowError and other similar exceptions are the kind of exceptions that we, as programmers, don’t want to deal with and the program should be allowed to terminate, because usually is not possible to recover from them.
All other exceptions, like File Not Found Exception, Array Index Out Of Bound Exception or Runtime Exceptions and others similar to these are usually exceptions that the program can recover from, so the programmer should catch and deal with them.
Why standardization within your software factory matters
Well, we all have been there. We all suffered from crappy feedback about what really happened. That make us dig into the system or application logging, trying to replicate the error in pre-prod or something like that, so we can debug a look for the root cause of the problem.
The standardization of the implementation process, code wise and exception handling prevents the programmer from re-inventing the wheel. There are multiple ways of doing it if we include all the applications and assets in a software factory. This allows that all programmers are speaking the same language.
Since there are standards that everyone should follow, it’s easier to find out if someone skipped it or has done it wrongly with a simple code review session. This will prevent the aforementioned problem.
How can we translate this when we are referring to an OutSystems factory? I’ll show you how we managed that on one large factory.
1- Create a Standard method to handle all the exceptions, that should log:
a. Espace where the exception occurred
b. Exact action where it occurred
c. Inputs parameters that generated the error
d. User impacted by the bad behavior of the code
e. Exception Message
f. What you, within your project feel relevant to log
Note that this action should be easy to use, to not be a constraint to use, so all that this action can do for their consumer it should do.
3- The Track log must quickly guide the programmer to the root cause of the problem.
4- The message propagated to the user should be human readable and should guide him/her to his next action.
5- The Following Pattern should apply to all server actions
6- Server actions whom need to expose a user’s defined exception should follow the following pattern. Note that HandleSpecificException should be an extended version of the standard one
We had already spoken about Exceptions and Errors. The only thing that we haven’t approach yet is something that a lot of people call also errors. Whether you are delivering a server action, a micro-service, or a public api’s, you are always aiming to deliver some kind of functionality, and within a functionality point of view there are exceptions to normal behavior that you want to control.
Those functional validations usually can generate Functional Errors and to handle them I propose the following approach:
With this pattern we have the flexibility to inform the consumer and the user of everything that might happen during the execution.
1. ErrorCode table: Holds Categories that identifies the exposed functionality
2. Code_Message Structure: will be used to return a single error or warning message.
a. Code — holds the value of the error code of the exposed functionality
b. Message — Actual message to be shown to the end user
3. Service_Return_Message
a. Success- Indicates if the execution has succeeded
b. HasWarnings- Indicates if the execution produced warnings
c. CodeMessageList- Holds all the error messages that where identified during the execution of a service
To finalize don’t forget a few good rules while writing the messages to be delivered to the end user.
In the end the content of that feedback to the user should:
· have a clear business focus
· clearly define what the problem was and why it happened
· be helpful
· be specific to the situation
· be understandable
· be polite and jargon free
· be rightly placed and clearly visible
. If possible, make sure that your business analyst, product owner, engagement manager or some other similar role in your project help you with this task. Developers taking ownership of this task usually is a bad idea.
I hope that you like this suggestion, please feel free to share your opinion on the comments bellow.
