Error Codes in Openpetra: Difference between revisions

From OpenPetra Wiki
Jump to navigation Jump to search
 
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
In petra every error message has got a code which helps to identify a messsage. In openpetra this is a little bit more important because here the message may be translated and unclear. The object TVerificationResultCollection for example provides a file named AResultCode and this may be one good position to place it.  
==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.


The task of this side is either to provide a ticket system which guarantees that a code is unique and it provides the start page for enhanced service information. As it was done in petra, in openpetra we will handle a code containing two parts, the name of the module and a running number. Each code number which is used by open petra has to be listed here includig a short description. Later - if necessary - a link to a more detailed page can be added.  
==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 '<code>Ict.Petra.Client.App.PetraClient.TPetraClientMain.StartUp</code>') and PetraServer (in the Constructor of the '<code>Ict.Petra.Server.CallForwarding.TCallForwarding</code>' Class).)


The error number contains of a module name like MODULE and a running number like MODULE.01 or else.  
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 '<code>GENC.0017V</code>' Error Code found in <code>\csharp\ICT\Common\StringChecks.cs</code>. All other Error Codes in the 'GENC.*' group are defined in <code>\csharp\ICT\Common\ErrorCodes.cs</code>, 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. <code>ErrorCodes.cs</code>), pointing to locations outside of that Class where other Error Codes of the same group are defined. Example: <code>GENC.0017V</code> Error Code).


== Error Codes Example ==
At the point of writing this documentation, Error Codes are defined in the following Namespaces:
* <code>Ict.Common.CommonErrorCodes</code> (in file <code>\csharp\ICT\Common\ErrorCodes.cs</code>)
* <code>Ict.Common.Ict.Common.Verification.TStringChecks</code> (in file <code>\csharp\ICT\Common\Verification\StringChecks.cs</code>)
* <code>Ict.Petra.Shared.PetraErrorCodes</code> (in file <code>\csharp\ICT\Petra\Shared\ErrorCodes.cs</code>)


* EXCAMPLE
** EXCAMPLE.01: Message ...
** EXCAMPLE.02: [[The message example.02]]


Please join the code and the number correctly at the first part of the line. This helps a user to find the information by using the search function. And the message itelf can contain a link o an other page. please do not use more than a line for the description.
===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.  


== Error Codes ==
====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 - <code>Ict.Common.Testing.TTestCommon.TestErrorCodesUniqueAcrossOpenPetra</code>. 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/

Latest revision as of 22:13, 2 March 2013

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/

Retrieved from ‘https://wiki.openpetra.org/index.php?title=Error_Codes_in_Openpetra&oldid=3432’