I think it's fair to say that a user should never have to see an error whilst they surf your site. Such wishful-thinking is far from reality, as we all know. All we can do is try and make it a little less confusing for them. After all, what could be worse than them having to come across the good old 404 page.



This doesn't need to look like this of course. We all know that, using the reserved form name of "$$ReturnGeneralError" we can create a form that can display the error in any format we desire. Adding to this form a field called "MessageString" we can even show this exact message to them. Still this is not perfect. Your users don't really want to have to read that there has been an "Incorrect data type for operator @Function", do they? What you want to do is let them know that things aren't going well, while at the same time, remaining from alarming them with techno-speak.

How do we do this:

So the first thing we do is create the $$ReturnGeneralError form and try and make as much like the rest of the site as possible. We want them to know there has been an error but without startling them at the same time. Maybe some subtle red text as the error message.

What can we do now? One idea is to show an alternate message that makes the error make more sense. This was an idea that was suggested to me quite a while ago. Something I have to admit I had forgotten about until a few days ago when Steve Cannon of Numedia mailed me a copy of such a database that he had created himself. This article is about how I've taken said database and tarted it up a little with a few of my own ideas that should make a great example of user-friendly error-reporing.

Step 1:

Instead of Domino's own errors, why not provide an alternate version in "English". Using the list I started to compile so many moons ago we can provide this alternative.

Steve has done this by creating a form and a view to store a list of alternatives to the error messages. The form is called "Error Configuration" and is used to store the Domino error message and its English translation. The view is called, surpise surprise, "Error Configurations" and is used as a lookup. Using Domino's own message as the key, we can do a lookup from our error-form and display the alternative instead.

The attached database has this form and view in it for your convenience. Aren't we good to you!? It also already has a set of documents in it that list the most common errors likely to occur. Personally I would create this list in a database called "errors.nsf" in the root. We can then rely on a centrally updated list rather than have to maintain it in several places.

On our new $$ReturnGeneralError form add two fields, one called MessageString and one called AltMessageString. In the AltMessageString field place the following formula:

msg := @DbLookup( "Notes" : "NoCache"; "" : "errors.nsf"; "LU_ERRCONFIG"; MessageString; 2 );
chkMsg := @If( @IsError( msg ); "No help found for this error"; msg );
chkMsg

This will display something that means a little more that than what Domino tells us. An example is shown below:



This makes a little more sense doesn't it. Now we need to decide whether to show these errors at all and whom to. Most users need not know any specifics of an error. All they really need is to be told that all is not well. How about we only show the details of the error when we are in "debug" mode. Let's assume that you have Designer access if you are developing it. In this case we can hide the error details using a small @Formula. In the database I have added a field called "ShowHelp" and in it this formula:

@If( @TextToNumber( @Subset( @UserAccess( @DbName ); 1) ) > 5; 1; 0 )

We can then have a hide-when formula on the error section that is simple !ShowHelp.

Step 2:

Having developed and tested the application as best you can, the user will then start to use it. More than likely they are going to see an error sooner or later. What should happen then? We should know about it, as the developers, as well. Because the $$ReturnGeneralError is a "special" type of form we can't automate this with a WebQueryOpen agent so we need to rely on the user to let us know instead. Easiest way to do this is to give them either a number to call or a contact address to e-mail. In the case of the e-mail we can even help them out a little with a link that helps build their message. Here is the formula for the link:

"<a href=\"mailto: webmaster@yourdomain.com?subject=An error occurred whilst I was browsing the intranet&Body=The error read:" + MessageString + "%0D%0DWhen I looked at this page: " + Path_Info + "%0D%0DUsing this browser: " + HTTP_User_Agent + ".\">Intranet Support Team</a>"

The email will then look something like:



All we need to do then is rely on their good nature to press the Send button. Maybe you could organise for a competition, whereby the user to report the most errors wins a nice prize?

So, there you go:

Download the database and hopefully after you've played with it for a while you'll have some ideas of your own as to how to improve your own methods of dealing with errors. You'll need to place it on a server as local databases return your access level incorrectly.

Thanks again for Steve Cannon for putting the time in to the initial idea for the Error Messages database.