Error Codes in Openpetra
Objective of Error Codes
In Petra 2.x, every error message has got an error code which helps to identify a message. In openPETRA this is even more important, because in openPETRA the message text and message title may be translated into any language and its meaning will be unclear to support staff who don't speak the language the message is shown in. The only way they can identify the error message in such a case is by looking up the error code.
Declarations of Error Codes
Error Code declarations can exist throughout OpenPetra (anywhere in Ict.Common* and Ict.Petra.Shared*, in theory). However, Error Code Namespaces need to be 'registered' in order for them to be used in the OpenPetra application. That happens at the startup of PetraClient (in Method '
Ict.Petra.Client.App.PetraClient.TPetraClientMain.StartUp') and PetraServer (in the Constructor of the '
Error Codes are deliberately allowed to be declared in several different Namespaces for maximum flexibility and to allow declaration of ErrorCodes close to the context in which they are used. Through that it is possible for several Namespaces to contain various (unique) Error Codes, also ones in the same group (e.g. 'GENC.*'). An example for that is the '
GENC.0017V' Error Code found in
\csharp\ICT\Common\StringChecks.cs. All other Error Codes in the 'GENC.*' group are defined in
\csharp\ICT\Common\ErrorCodes.cs, but this one is defined in a different Namespace to place it close to the context where it is used. (It is a good idea to put a comment into the place where many Error Codes are defined (e.g.
ErrorCodes.cs), pointing to locations outside of that Class where other Error Codes of the same group are defined. Example:
GENC.0017V Error Code).
At the point of writing this documentation, Error Codes are defined in the following Namespaces:
Uniqueness of Error Codes
Error Codes need to be unique in the whole OpenPetra application to prevent that different Errors or Warning would use the same Error Code.
Automated Check for the Uniqueness of Error Codes
To uncover any duplicate Error Codes declarations across all Namespaces in which they are registered, a NUnit Test exists -
Ict.Common.Testing.TTestCommon.TestErrorCodesUniqueAcrossOpenPetra. That NUnit Test will fail if duplicate Error Codes are defined in any of the 'registered' Namespaces, so duplicates will be automatically uncovered in this way.
Error Code Handling in openPETRA
The object TVerificationResult provides the Property 'ResultCode'. The error code of a particular error needs to be assigned to this property.
When an error message is displayed, e.g. in a MessageBox, the 'ResultCode' is to be displayed in a separate line at the end of the message.
Central Inventory of Error Codes
We have plans for writing a
nant task that will generate a HTML file (a bit like our auto-generated DB documentation, found at [http://dbdoc.openpetra.org]) that will list all currently used Error Codes across the whole OpenPetra application, their Namespace, their ShortDescription and FullDescription, and their ErrCodeCategory.
That nant task would be run daily as part of our daily build scripts and if that HTML file can get uploaded to a central location (like [http://dbdoc.openpetra.org]) then it could be used for reference - not only by the software engineers (who can also determine the next valid unused Error Code by that) but later also for people who will support deployed OpenPetra installations. The texts in the HTML page will always be in English, whereas the Error Code texts of OpenPetra can be translated into any language; by looking up an Error Code on that HTML page the support person can find out what error the user has got on screen even if the error text cannot be understood by the support person as the error text might be in a language that he/she doesn't know!
That HTML page will then replace the wiki page Central Inventory of openPETRA Error Codes, which needs to be manually maintained.