Overview

 

After having installed the OutSystems Agile Platform, you get two kinds of error pages: the ones served by IIS and the ones served by the Agile Platform. These pages are default content, are not customized for your specific customer project, and doing so will definitely make your applications look more professional and definitely add value to them.

 

This simple how-to explains how you can create custom error pages using the OutSystems Agile Platform (4.1+) and configure them. These pages can then replace the default error pages provided by OutSystems and IIS. The goal with this how-to is to allow you to create error pages with the OutSystems Platform and use them as error pages.

 

This howto focuses on 2 of the possible options:

  1. Replace the global error handlers (for all eSpaces);

  2. Create custom error handlers for one or more eSpaces.

 

You can use both options at the same time (i.e. create a global error handler using OutSystems and then a custom one to be used only by some eSpaces).

 

 

What you need

 

You will need the following:

  - eSpace(s) with the error page(s) to be used;

  - extension HTTPRequestHandler (bundled with Enterprise Manager 4.1+);

  - Component FactoryConfiguration

 

 

Creating the error pages

 

Remember that an error page may prompt in adverse conditions, so make sure to keep functionality in the error page to a minimum. Specifically, you should minimize the use of actions in the preparations or AJAX. Remember, if there is an error condition on your server, it will also affect your error pages, so keep them as simple as possible, while allowing you to obtain the desired result.

 

If you wish to make any sort of processing using the URL being accessed, create a text variable named aspxerrorpath in your error page - its value will be filled in with the URL being accessed.

 

After you make the design of the web page destined to be used as error page, you need to add a call to the SetStatusCode action in HTTPRequestHandler extension to the preparation of the screen. You can find a list of codes that can be used in [2]. Sample usages:

 

  - 404 Not Found

  - 500 Internal Server Error

 

This step is destined to make sure that the correct error codes are passed to browsers and search engines.

 

 

1. Replace the global error handlers

 

After having the error page(s) published, you simply need to create a redirect rule in IIS for the following files:

  - customHandlers/notfound.aspx;

  - customHandlers/internalerror.aspx;

 

Simply redirect them individually to the correct page (e.g. /errorpages/Error404.aspx) using IIS redirect feature, and remember to add $Q in order to get the parameters being passed (in case you need them). Check [1] for more details on IIS Redirect parameters.

 

 

2. Create custom error handlers for one or more eSpaces.

 

For this scenario you will need FactoryConfiguration. You can donwnload the component from the TechCenter components in the Agile Network. After having installed the component, simply create a configuration rule that replaces the default error handlers with the custom ones you want. Example below:

 

<?xml version="1.0" encoding="UTF-8"?>

<xsl:stylesheet version="1.0" xmlns:xsl="https://www.w3.org/1999/XSL/Transform">

 

    <xsl:output method="xml" indent="yes" encoding="UTF-8"/> 

 

    <xsl:template match="@*|node()">

        <xsl:copy>

            <xsl:apply-templates select="@*|node()"/>

        </xsl:copy>

    </xsl:template>

        

    <xsl:template match="/configuration/system.web/customErrors/error">

      <xsl:copy>

        <xsl:attribute name="statusCode">404</xsl:attribute>

        <xsl:attribute name="redirect">/errorpages/Error404.aspx</xsl:attribute>

      </xsl:copy>

    </xsl:template>

 

</xsl:stylesheet>

 

 

Replacing static content error pages

 

By default, IIS has 2 kinds of pages that it serves in case of error:

  - When an error occurs in a page that is being handled by ASP.NET, the error pages configured in it (the object of this post) are served; that includes all requests to contents like .aspx, .asmx, .ascx, ... In a standard Agile Platform installation, these pages are the default black-and-white "There was an error processing your request" pages;

  - However, for static content, the default IIS error pages are served. Static content means .html, .js, .css, .png, ...

 

Here you have multiple options, from which 2 are presented:

  - Configure IIS to handle all content with ASP.NET. For that, in the VDIR properties (one eSpace) or Default Web Site properties (all eSpaces), under Properties | Home Directory, click the Configuration button and add a global handler for all file extensions, without validating if the content exists, and use the same handler as for .aspx content;

  - Manually configure each VDIR (one eSpace) or the Default Web Site (all eSpaces) to use the error pages you created as handlers for the desired error codes. You can do that under Properties | Custom Errors, by reconfiguring entries as being of message type URL and inputting the desired url (e.g. /errorpages/Error404.aspx);

 

 

Finally

 

A special note regarding Agile Platform for Java: while this specific post is focused on IIS, most of the concepts are directly translatable to their JBoss counterparts. The only major difference is that you cannot use Factory Configuration (it only works with IIS and for customizing web.config entries), limiting the possibility of option 2 - configurating eSpaces individually. Later on I will post a reply detailing how to achieve the same result with the Agile Platform for Java.

 

Feel free to comment or correct whatever is said above! You may also contribute with your particular solutions for the same problem - I am sure that this is not the first time the subject has been brought up, and probably many projects already have something similar to this implemented.

 

 

References

 

[1] Redirect Reference (IIS 6.0)

https://www.microsoft.com/technet/prodtechnol/WindowsServer2003/Library/IIS/41c238b2-1188-488f-bf2d-464383b1bb08.mspx?mfr=true

 

[2] RFC 2616 - section 10 (Status Code Definitions)

https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html