Customizing Error Messages
In Microsoft Office XP, you can customize error messages to provide additional information about an error. When users can find problem-solving information on their own, they are less likely to call your support staff.
Adding value to error messages
Error messages, or alerts, are displayed when a user attempts an action the computer cannot perform. For example, if a user tries to print a document on a network printer without first installing a printer driver, the error message "No printer available" is displayed. If the user does not know how to install a network printer, the user will probably click OK or Cancel and call the support staff for assistance.
In Office XP, you can extend error messages — that is, you can customize some error messages to direct users to more information about the error encountered. To do so, link a custom button in the error message box to additional information on a Web site. By pointing the user to comprehensive or updated information on a Web site, you potentially reduce user frustration and increase productivity.
For example, you can create a button in the "No printer available" error message box to connect users to an intranet site with instructions for installing a network printer.
Extending custom error messages on a network
Some Office XP error messages are extended by default, leading users directly to the Microsoft Office Web site. However, you can extend these error messages to point to a site on your intranet. Additionally, there are error messages that are not extended by default that you can also customize.
Whether you customize an error message or redirect a default error message, you must create Web pages with information for how users can either correct or understand the problem encountered. If you redirect a user to a Web page for each custom error, you must also provide an Active Server Pages (ASP pages) file that resides on the Web site to manage which Web page is displayed to a user.
Expanding the use of custom error messages
Linking a custom error message to a Web page that contains information for solving a problem is helpful to the user. But if you create your own Active Server Pages (ASP pages) file, you can apply custom solutions to benefit you and the support staff — not just the users.
If you create an ASP file to customize error messages, your technical support staff should benefit by:
- Receiving fewer calls for assistance
Custom error messages can help reduce calls to the support staff. For example, you can link a "Server is down" error message to a Web page through an ASP file to analyze the occurrence of the error message and also include a segment of script code to notify the support staff that a user has probably experienced a possible network problem.
When a server goes down, you can also link the error message to a Web page with status information about the server or the network. When the users see that you are working on the problem, they are less likely to flood the support staff with calls for technical assistance.
- Collecting valuable information about errors users encounter
You can take custom error message routing a step further and create an ASP file to collect and forward information about error messages to the support staff through e-mail or a pager. This use of customized error messages keeps the support staff informed about current issues and helps them respond faster.
Suppose your organization has a system of Help pages in an intranet site, and you have linked error messages to those pages by using the Help Desk button in each error message box. With an ASP file you redirect users from the Help information on your intranet site to either a Web page or a generic Help site where the user can selectively browse for more information.
The following shows how an ASP script is used in extending error messages:
- When a user encounters an error message, the user can click the Help Desk
button for more information.
- The ASP file checks the error message
number, determines which Web page applies, and then redirects the
user's browser to that Web page.
- If the error message number does not match any of the predefined error message numbers listed in the ASP file, the ASP script can connect the user to a generic Help page for more information (see the
case else script language usage).
Toolbox You can look up detailed information about custom error messages (including error numbers and error categories) in the Microsoft Excel workbook Errormsg.xls. Errormsg.xls is installed by default when you run the Office Resource Kit Setup program. For more information, see Supplemental Documentation in the Toolbox.
Creating custom error messages
The task of creating and implementing your own custom error message consists of the following four steps:
- Gather error numbers, globally unique
identifiers (GUIDs) for each application, and country codes.
- Create Web pages that are linked to your
custom error message.
- Create the ASP files for your custom
error message.
- Activate the custom error message.
Note This process documents extending a custom error message through the use of ASP scripting. If you want to use a Common Gateway Interface (CGI) script, refer to the CGI reference manual for more information about CGI scripting.
At the end of this process, you have the following components:
- A functioning ASP page
- A Web page with information or help about
your custom error message
- Updated Windows registries on users'
computers
- Functioning custom error messages
Gathering information for custom error messages
The first step in extending an error message is to collect the following information:
- Error message number
Each error message in an application has a number, which is stored in the registry. For example, error message number 2202 in Microsoft Access is "You must install a printer before you design, print, or preview." This number is not required if you plan to redirect all error messages to a single Web page.
- GUID
A globally unique identifier (GUID) identifies the application to which the error message belongs. The GUID is required and can be found by adding the following line of code to either a macro, module, or running it directly from the Immediate Window of the Visual Basic Editor.
MsgBox Application.ProductCode
The GUID for each release of an Office application changes for each build. This means, the SR-1 release is going to be different than the original release of the product. If you implement custom error message handling, you may be required to update the ASP files if they identify the application that called it by the GUID it submits with the error it spawns.
- Country code (the LCID, or locale ID)
If you plan to redirect error messages based on the current default language of Office, you must provide the LCID, which allows the ASP script to determine the locale of Office XP. This parameter is only necessary if you are in a multilingual environment. Find the LCID by running the following command from the Immediate Window in Visual Basic® for each application:
MsgBox Application.LanguageSettings.LanguageID(msoLanguageIDUI)
You can replace the msoLanguageIDUI with other parameters to find the language for the installed Help, EXE mode, previous install language, and the "installed" (default) language the application was installed to use. Usually, you want to test for the user interface language since that determines what language the user was working in when the error occurred. Testing for the Help language might be helpful for instances when the Help system is the "native" language spoken where the application is being used.
Toolbox You can look up detailed information about custom error messages (including error numbers and error categories) in the Microsoft Excel workbook Errormsg.xls. Errormsg.xls is installed by default when you run the Office Resource Kit Setup program. For more information, see Supplemental Documentation in the Toolbox.
Creating a Web page for custom error messages
You must create a Web page to provide users with custom information for error messages they encounter. For example, when a user encounters the "No printer found" error message and then clicks the button linked to the intranet Web site, you must have a Web page describing how to solve the printer error problem.
You can redirect multiple error messages to a single Web page if you need to. If properly created, you can use one Web page to handle multiple error messages and reduce the number of registry entries. A single Web page is also the best solution if you do not want to create an ASP script.
If you choose to implement an ASP script, place your Web pages on your server and put the ASP file in the root directory of the Web server to which you are pointing custom error messages.
Toolbox For simple implementations of customizable error messages, such as a general question and answer page, start with the following sample Web pages: Alert.asp, Alert.htm, Alert2.asp, Alert2a.asp, and NYI.htm. These files are installed by default when you run the Office Resource Kit Setup program. For more information, see Supplemental Documentation in the Toolbox.
Creating an ASP file for custom error messages
When users click the custom button in an error message box, an Active Server Pages script directs their browsers to a Web page that provides information about the error and allows them to take action accordingly.
Tip ASP files are designed to only run on Microsoft Windows® operating systems. For optimal performance, use Windows NT® Server 4.0 or later and Internet Information Server (IIS).
There are three ways to create or update an ASP file. You can:
- Use the ASP generator
The ASP generator (an Excel workbook called Aspscrpt.xls) is the quickest and easiest way to create a generic ASP file. However, not all programming or scripting options are available, and the script cannot handle large numbers of error messages. You need Excel 97 or later to use the ASP generator.
- Write your own script
This method requires knowledge of Visual Basic programming language, ASP scripting, and the Microsoft Script Editor (though you can use a text editor if you prefer). It also requires extra development time and a more extensive knowledge of scripting and Visual Basic. It is advised to copy an existing ASP script to get started.
Use the ASP generator
If you are going to create ASP files for a small number of custom error messages, the simplest solution is to use the ASP generator (Aspscrpt.xls). The template requires information about each error message you are going to customize.
Toolbox Use the Excel workbook Aspscrpt.xls (ASP generator) to create an ASP file for handling custom error messages. You need to know the error message number, GUID, and LCID for each custom error message, as noted in the "Gathering information for custom error messages" section earlier in this topic. Aspscrpt.xls is installed by default when you run the Office Resource Kit Setup program. For more information, see Supplemental Documentation in the Toolbox.
To use the ASP generator, you need the following:
Running this command displays the literal GUID you need to supply (including the brackets) to the ASP. Substitute the MsgBox command with either Print or ? (question mark) to obtain a textual printout you can copy into your code.
- The LCID for each application
Find the LCID by running the following command from the Immediate Window in Visual Basic for each application:
MsgBox Application.LanguageSettings.LanguageID(msoLanguageIDUI)
You can replace the msoLanguageIDUI with other parameters to find the language for the installed Help, EXE mode, previous install language, and the "installed" (default) language the application was installed to use.
To generate an ASP file
- Start Excel, and open the file
Aspscrpt.xls.
- In the Enter the default URL for error messages not listed below box, type the URL of the default Web page.
The default Web page is a generic page used to handle all error messages without a unique Web page assigned to them.
- In the Enter the physical, or actual, path of the base URL box, type the path
to the destination directory where the new ASP file is stored.
- Fill in the LCID, Microsoft Installer GUID, Error Message Number, and URL to the Destination Web Page columns
for any error messages you want to customize.
- Click Go.
The new ASP file is created and stored where you specified.
Modify a sample ASP script
If you plan to implement a larger number of custom error messages, you can modify a sample ASP script.
Toolbox The Office Resource Kit includes sample ASP and HTML files to help you create a custom error message system. Create your own ASP and HTML files from the files Alert.asp, Alert.htm, Alert2.asp, Alert2a.asp, and NYI.htm. These sample files are installed by default when you run the Office Resource Kit Setup program. For more information, see Supplemental Documentation in the Toolbox.
Example Code #1
The following ASP code from the sample file Alert.asp handles four custom printer-related error messages (remember, the GUID used may not apply in your situation, so use Msgbox Application.ProductCode to be sure you are testing for the correct GUID):
<% response.expires=0
alertNum=request.queryString("alrt")
LCID=request.queryString("HelpLCID")
GUID=request.queryString("DCC")
select case (alertNum & GUID & LCID)
case "197573{00000409-78E1-11D2-B60F-006097C998E7}1033" ' for Word
response.redirect("http://helpdesk/office10alerts/printer.htm")
case "197574{00000409-78E1-11D2-B60F-006097C998E7}1033" ' for Word
response.redirect("http://helpdesk/office10alerts/printer.htm")
case "197575{00000409-78E1-11D2-B60F-006097C998E7}1033" ' for Word
response.redirect("http://helpdesk/office10alerts/printer.htm")
case "197576{00000409-78E1-11D2-B60F-006097C998E7}1033" ' for Word
response.redirect("http://helpdesk/office10alerts/printer.htm")
case else
response.redirect(http://helpdesk/office10alerts/FAQ.htm)
end select %>
Example Code #2
The following script code may be easier to maintain for large numbers of custom error messages. The case structure allows you to group all the LCID messages together in one place. Then the script tests for all the GUIDs and then the error message number. This process might run slightly faster on most systems.
<% response.expires=0
alertNum=""&request.queryString("alrt")
LCID=request.queryString("HelpLCID")
GUID=request.queryString("DCC")
select case (LCID)
case "<insert LCID for Language here>"
select case (GUID)
case "<insert GUID for Word here>"
select case (alertNum)
case "197573"
response.redirect("http://helpdesk/officealerts/wdprinter.htm")
case "197574"
response.redirect("http://helpdesk/officealerts/wdprinter.htm")
case else
response.redirect("http://helpdesk/officealerts/wdFAQ.htm")
end select
case "<insert GUID for Excel here>"
select case (alertNum)
case "197573"
response.redirect("http://helpdesk/officealerts/xlprinter.htm")
case "197574"
response.redirect("http://helpdesk/officealerts/xlprinter.htm")
case else
response.redirect("http://helpdesk/officealerts/xlFAQ.htm")
end select
case else
response.redirect("http://helpdesk/officealerts/catchall.htm")
end select
case else
response.redirect("http://helpdesk/officealerts/NoSuchLCID.htm")
end select %>
To modify this sample script for your custom error messages, open the file in Microsoft FrontPage® or another ASP editor and substitute the GUID variables (everything within the parenthesis after the case statement) with your own values.
The following values and variables are used in the sample ASP scripts:
- LCID
This number is used to identify the locale of Office XP. The LCID for the currently configured "default" language (Tools menu, Language, Set Language…, Language dialog) is the number supplied (regardless of the install language).
If the information passed to the ASP file from the Office application that spawned an error message matches the information in the case statement, then the response.redirect action is initiated — in this case, the Web page assigned to an extended error message is displayed.
All of the error messages in this sample script reference the same Web page. Any error messages not covered in a case statement are directed to the FAQ.htm Web page (the case else test condition is a catchall for any errors not tested for in previous case statements). A case else must ALWAYS be the last entry in the select case series of test conditions. You can easily add new case test conditions with response.redirect functions calling other Web pages by copying an existing entry and pasting it anywhere between the select case and case else statements. Then change the Web page called in the response.redirect function.
Note Two additional sample scripts, Alert2.asp and Alert2a.asp, provide examples of how you can extend the functionality of the ASP file. Alert2.asp prompts users to enter an explanation of the error. After users type their feedback and click Submit, they are redirected to Alert2a.asp, which contains a message thanking them for their feedback.
Write your own ASP file from scratch
You can write your own ASP file by using the Microsoft Script Editor available in the Microsoft Word Macro… dialog (Tools menu) or JavaScript, both of which are supported by Windows NT Server and IIS. When you write your own ASP file, you can add the ability to capture information about an error and use it to perform more advanced actions.
For example, a custom ASP file can generate dynamic HTML or redirect a browser to go to a different page, depending on the values sent to the ASP file from the browser. It can also capture the values from an error message and write them to a log file. A network administrator can use the log file to help solve common network problems.
Activating custom error messages
You activate a custom error message by setting a registry entry that is recognized by each application. You can use any of the following tools to set a registry entry:
Note When you enable custom error messages by using a system policy, the policy settings override any existing custom error messages registered in the HKEY_CURRENT_USER\Software\Microsoft\Office\10.0\Application
\CustomizableAlerts subkey.
To activate all custom error messages, add the following registry key to a user's registry if the key isn't already there:
HKEY_CURRENT_USER\Software\Microsoft\Office\10.0\Common\General
\CustomizableAlertBaseURL
The error message number, GUID, and LCID are automatically appended to the URL by the application that spawned an error. This allows the ASP script to correctly route the user to the Web page that contains more information about an error. For the ASP file to function properly, append a question mark (?) to the end of the URL. This allows you to pass the error message number, GUID, and LCID as parameters for use within the ASP file. The following is an example of a base URL:
http://localhost/mypage.asp?
The default BaseURL shipping with Office XP is:
http://OfficeUpdate.Microsoft.com/office/redirect/fromOffice9/ExtendedAlerts.htm
?DPC=%ProductCode%&AppName=ApplicationName%&HelpLCID=%HelpLang%&UILang=%UILang%&
If you choose to configure your ASP file to handle any additional parameters, such as the computer name, you will need to add an ampersand (&) to the end of the registry value string so the default parameters are added when the link is activated. The following is an example of a base URL query string:
http://localhost/mypage.asp?ComputerName=%CompName%&
When you change the URL, you can also update the custom button text that appears on the error dialog by using the following registry subkey:
HKEY_CURRENT_USER\Software\Microsoft\Office\10.0\Common\General
\CustomizableAlertDefaultButtonText
Adding text to this button should be short and include an ampersand (for a hotkey) that is not used elsewhere on the error dialog.
Activating a custom error message
If you want to enable a single error message, add an entry for the error message to the following registry subkey (substitute Application with Word, Excel, etc):
HKEY_CURRENT_USER\Software\Microsoft\Office\10.0\Application\CustomizableAlerts
Each registry entry has a related name and value entry. The registry name is the numeric ID for the error message, and the registry value is the custom text you add for users to see on the custom button for the error message.
For example, to add a custom error message for error message number 46 (a printer error) in Word, you can change the following registry subkey:
HKEY_CURRENT_USER\Software\Microsoft\Office\10.0\Word\CustomizableAlerts
Value name: 46
Data type: REG_SZ (string)
Value data: "<custom text>"
Add custom text to the button similar to:
&Printer Help
The "&" allows use of the ALT+P shortcut key combination by the user to activate the custom error action.
Activating custom error messages with a system policy
Custom error messages activate when the correct value settings are entered into the Windows registry. Each computer on your network must be updated to activate custom error messages completely, after you have created an Active Server Pages file. You can activate one or all of the custom error messages by using the System Policy Editor.
Activate all error messages with a system policy
If you want to enable all custom error messages for all Office XP applications, use the System Policy Editor to set the following policy in the policy tree:
Microsoft Office XP | Customizable error messages | Base URL
Your new URL must point to the ASP page you created for the custom error messages. The error message number, GUID, and LCID are automatically appended to this base URL so the ASP script can correctly supply the defined HTML page. For the ASP file to function properly, you must type a question mark (?) at the end of the URL to submit the error message number, GUID, and LCID parameters to the ASP page. The following is an example of a base URL:
http://localhost/mypage.asp?
If you decide to create an ASP file to handle any additional parameters, such as the computer name, add an ampersand (&) to the end of the query string. The following is an example of a base URL with a parameter named ComputerName added:
http://localhost/mypage.asp?ComputerName=%CompName%&
Activate one error message with a system policy
If you want to activate a single error message, use the System Policy Editor to add an entry for the error message to the List of error messages to customize policy.
For example, to add a custom error message to Word, enforce the following policy:
Microsoft Word 2002 | Customizable error messages \ List of error messages to customize
In the Settings for List of error messages to customize work area, click the Show button. Click Add…, and then type the name and value for the error message. The name is the numeric ID for the error message, and the value is the text for the custom button for the error message (what the user sees on the button).
Removing or disabling custom error messages
You might decide to disable or remove one or more custom error messages. For example, if you do not want users to have access to the Internet and you do not want to redirect them to an intranet site, you can disable or remove all custom error messages.
You can use a system policy to disable or remove custom error messages. Setting a system policy to "clear" removes that selected policy from a user's computer when the policy file is implemented on the primary domain controller.
You can also use the Custom Maintenance Wizard to remove or disable custom error messages by navigating to the Change Office User Settings page and searching for the Customizable error messages entries within each application and setting them appropriately.
Note If you disable a custom error message, the custom button in the error message box no longer appears. The error message will function as originally designed.
Disabling custom error messages for all applications
If you want to disable all custom error messages for all Office XP applications, delete the URL in the following registry subkey:
HKEY_CURRENT_USER\Software\Microsoft\Office\10.0\Common\General
\CustomizableAlertBaseURL
The CustomizableAlertBaseURL entry is the master switch for custom error messages. If a URL is not listed in this entry, none of the error messages in Office are customizable.
When you remove the URL, be sure to remove any custom button text from the associated registry subkey:
HKEY_CURRENT_USER\Software\Microsoft\Office\10.0\Common\General
\CustomizableAlertDefaultButtonText
Disabling custom error messages for a single application
If you want to disable all custom error messages for a single application, such as Microsoft Word, remove any customized error message listed in the following registry subkey:
HKEY_CURRENT_USER\Software\Microsoft\Office\10.0\Application
\CustomizableAlerts
Removing a single custom error message
If you want to remove a single error message, delete the entry for that error message from the following registry subkey:
HKEY_CURRENT_USER\Software\Microsoft\Office\10.0\Application
\CustomizableAlerts
Each registry entry consists of a name and a value. The name is the numeric ID for the error message, and the value is the text you added to change the text that appears on the custom button in the error message box.
For example, to remove a custom error message for error message number 46 (a printer error) in Word, you would delete the following registry value entry:
HKEY_CURRENT_USER\Software\Microsoft\Office\10.0\Word\CustomizableAlerts
Value Name: 46
Disabling custom error messages after deploying Office
If you have already deployed Office XP, and you want to disable or remove custom error messages, you can use the System Policy Editor.
Disable all custom messages for all Office applications
If you want to disable all custom error messages for all Office XP applications, use the System Policy Editor to clear the following policy:
Microsoft Office XP | Customizable error messages | Base URL
Disable all custom messages for a single application
If you want to disable all custom error messages for a single application, such as Microsoft Word, use the System Policy Editor to clear the application's List of error messages to customize policy.
For example, to remove custom error messages from Word, you would follow the policy path Default User | Microsoft Word 2002 | Customizable error messages and clear the List of error messages to customize check box.
Remove a single custom error message
If you want to remove a single error message, remove the entry for that error message from the List of error messages to customize policy.
For example, to remove a specific custom error message from Word, use the following policy:
Microsoft Word 2002 | Customizable error messages | List of error messages to customize
In the Settings for List of error messages to customize area, click Show, and then select the Value Name and click the Remove button.
If you do not want to enable custom error messages for your organization, you can disable them by using the Office Custom Installation Wizard or Custom Maintenance Wizard to remove the URL entry from your users' registries.
The System Policy Editor is another tool you can use to disable custom error messages by removing the URL entry from your users' registries.
|
microsoft.com Home
