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 'Ict.Petra.Server.CallForwarding.TCallForwarding' Class).)

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:

• Ict.Common.CommonErrorCodes (in file \csharp\ICT\Common\ErrorCodes.cs)
• Ict.Common.Ict.Common.Verification.TStringChecks (in file \csharp\ICT\Common\Verification\StringChecks.cs)
• Ict.Petra.Shared.PetraErrorCodes (in file \csharp\ICT\Petra\Shared\ErrorCodes.cs)

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

See the generated list of already existing error codes in OpenPetra: https://ci.openpetra.org/job/OpenPetraCodeDoc/doclinks/1/