You are on page 1of 7

Integration Error Handling

status

DONE

Usefull links

Installing Dispatcher on Apache webserver: htt


ps://docs.adobe.com/docs/en/dispatcher/disp-i
nstall.html
Configuring custom error pages in Apache:
http://httpd.apache.org/docs/2.4/custom-e
rror.html#configuration
http://httpd.apache.org/docs/2.2/mod/core
.html#locationmatch

What is Error Handling


Http error codes have to be handled on two levels:
1. Dispatcher (dispatcher must be configured in front of AEM/CQ instance)
2. Application

Dispatcher level error handling


By default, the content served for custom error pages such as the 404 and 500 are not
cached
DispatcherPassError and ErrorDocument directive needs to be configured in Apache in
order to serve error documents from the webserver level
Do the following needs to be done for configuring dispatcher level error handling:
1. Install dispatcher module on Apache web server
2. In the Apache configuration (httpd.conf) set DispatcherPassError 1
Dispatcher does not spool an error response to the client (where the status code
is greater or equal than 400), but passes the status code to Apache, which e.g.
allows an ErrorDocument directive to process such a status code.

<IfModule disp_apache2.c>
# All your existing configuration
DispatcherPassError 1
</IfModule>

Detailed explanation can be found in official documentation https://docs.


adobe.com/docs/en/dispatcher/disp-install.html

3. In AEM/CQ, override the default error handler script and create custom error
pages (described in next section Application level error handling)
Then configure your ErrorDocument in httpd.conf which will point to custom error
page. This directive specifies mapping - which content page should be displayed
when error with specific status code occurs

What is Error Handling


Dispatcher level
error handling
Application level
error handling
Add Error handling to your
project
Including required
dependencies
Create the Error Handler
configuration
Create the Error
Pages
Create the Error
Pages configuration
settings
Reference Error
Pages configuration
settings from your
project root

<LocationMatch \.html$>
ErrorDocument 404 /404.html
#ErrorDocument <ANY OTHER ERROR CODE>
<PATH IN YOUR DOCROOT>
</LocationMatch>

Detailed explanation can be found in official documentation:


http://httpd.apache.org/docs/2.4/mod/core.html#locationmatch
http://httpd.apache.org/docs/2.4/custom-error.html#configuratio
n

4. Example LocationMatch and ErrorDocument configuration for multitenant


environment

<LocationMatch /content/tenant1>
ErrorDocument 404
/content/tenant1-404.html
ErrorDocument 403
/content/tenant1-403.html
</LocationMatch>
<LocationMatch /content/tenant2>
ErrorDocument 404
/content/tenant2-404.html
ErrorDocument 403
/content/tenant2-403.html
</LocationMatch>
<LocationMatch /content>
ErrorDocument 404
/content/fallback404.html
ErrorDocument 403
/content/fallback403.html
</LocationMatch>

With above configuration if someone request a page, that may lead to any of above error
code, in that case page will be served by CQ dispatcher and not by Publish instance. This
will also avoid unnecessary load on publish instance.

Application level error handling


Error handling on the application level is handled via redirects
The Sling error handler will redirect to the error page of the tenants context, these pages
are the same as configured in the dispatcher
To be able to redirect to the right error page, we will use the cnf and cnfmgr introduced in
AEM 6.1
Configuration management functionality (which was introduced in AEM 6.1) needs to be
integrated into AEM 6.0 instances explicitly (these are currently used by EON, and they
dont provide this functionality by default)

For more information about Error handling (technical implementation concept and
detailed description) check the confluence page here

Defines how to support error codes for ErrorDocument handling:


0 - Dispatcher spools all error responses to the client.
1 - Dispatcher does not spool an error response to the client (where the status code is
greater or equal than 400), but passes the status code to Apache, which e.g. allows an
ErrorDocument directive to process such a status code.
Code Range - Specify a range of error codes for which the response is passed to
Apache. Other error codes are passed to the client. For example, the following
configuration passes responses for error 412 to the client, and all other errors are
passed to Apache: DispatcherPassError 400-411,413-417

Add Error handling to your project


Java package location

eon-aem-foundation\foundation-core

Package name

com.eon.aem.foundation.errorhandling

Mock-up Content

errorhandler-mock-content.zip

Mock-up Configuration

errorpagehandler-mock-config.zip

eon-aem-foundation
Inside the eon-aem-foundation a package has been created that can be reused by all projects and contains the implementation of application
level error handling functionality.
errorpagehandler-mock-config.zip contains example error handler configuration, which works with provided example content. It has to be
adjusted to your project needs.
errorhandler-mock-content.zip contains example content for testing application level error handling. It works with basic Geometrixx and
Geometrixx Outdoor project, which are always included in AEM instance after installation.

Including required dependencies


Configuration Manager classes are implicitly included in AEM 6.1 dependency.
But EON is using AEM 6.0 instances. It means that dependency to Configuration Manager classes needs to be explicitly added in project pom
files.

Making Configuration Manager available for AEM 6.0 project


<!-- AEM 6.1 - For Configuration Manager API is part of a cq-quickstart artifact -->
<dependency>
<groupId>com.day.cq</groupId>
<artifactId>cq-quickstart</artifactId>
<classifier>apis</classifier>
<version>6.1.0</version>
</dependency>
<!-- AEM 6 -->
<dependency>
<groupId>com.adobe.aem</groupId>
<artifactId>aem-api</artifactId>
</dependency>

Configuration Manager maven dependency


<!-- In order to be able to call Configuration Manager classes in source code we
need to add dependency -->
<dependency>
<groupId>com.adobe.granite</groupId>
<artifactId>com.adobe.granite.confmgr</artifactId>
<version>1.0.0</version>
<scope>provided</scope>
</dependency>

We need to adjust Felix build plugin because Configuration Manager bundle wants to use higher version of org.apache.sling.api.resource
API then AEM 6.0 provides (it wants to use version which is provided in AEM6.1)

Apache Felix build plugin adjustment


<plugin>
<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
<configuration>
<instructions>
<Import-Package>
!org.apache.sling.api.resource;version="[2.8,
3)",org.apache.sling.api.resource;version="2.5.0",*
</Import-Package>
<Export-Package>
com.eon.aem.foundation,
com.eon.aem.foundation.errorhandling,
com.eon.aem.foundation.errorhandling.impl
</Export-Package>
</instructions>
</configuration>
</plugin>

All these steps needs to be done because Configuration Manager is an AEM6.1 functionality but EON uses AEM 6.0

Create the Error Handler configuration


Error handler configuration is stored in JCR under /conf folder, it defines mapping between error codes and error pages which needs
to be displayed when speciffic error occures
cq:conf property pointing to specific project configuration needs to be added into project root jcr:content
Error pages to which displays error messages needs to be created in the respective content tree

Create the Error Pages


Each project should have an own error pages in their content tree
You can have one error page for all the errors or create a separate error pages for each specific error codes (403,404,500 ...)
Example error pages defined within Geometrixx and Geometrixx Outdoors content tree can be found in errorhandler-mock-content.zip packag
e. It is used for demonstration how application level error handling can be used.

Create the Error Pages configuration settings

/conf
+ global
+ settings
+ errorPages (Global error page configuration is used if there is no
tenant configuration defined)
- 404 => points to global 404 error page
- 403 => points to global 403 error page
- 500 => points to global 500 error page (this is a fallback error
page if error pages are not defined for the occurring error)
+ eon.de (tenant)
+ settings
+ errorPages
- 404 => points to 404 error page in German project
- 403 => points to 403 error page in German project
- 500 => points to 500 error page in German project (this is a
fallback error page if error pages are not defined for the occurring error)
+ eon.sw (tenant)
+ settings
+ errorPages
- 404 => points to 404 error page in Sweden project
- 403 => points to 403 error page in Sweden project
- 500 => points to 500 error page in Sweden project (this is a
fallback error page if error pages are not defined for the occurring error)

Example configuration can be found in errorpagehandler-mock-config.zip which works with example content package and its purpose is to
demonstrate how application level error handling works

Reference Error Pages configuration settings from your project root


In the content strucuture the corresponding config node has to be referenced.

/content
+ jcr:content
- cq:conf = "/conf/global"
+ eon.de
+ jcr:content
- cq:conf = "/conf/eon.de
+ eon.sw
+ jcr:content
- cq:conf = "/conf/eon.sw"

Example cq:conf configuration on Geometrixx and Geometrixx Outdoors project root node can be found in errorhandler-mock-content.zip pac
kage. It is used for demonstration how application level error handling can be used.