Video Demo: Error Handing in AEM

I recently published an article on how to customize your website error pages. Error handling in AEM is crucial to the customer experience and the security of your site. For example, creating a custom 404 error page helps maintain site visitor confidence by keeping them within a consistent site experience.

For those who like a more visual experience, I've created this video.

More Videos from 3|SHARE

You can visit 3|SHARE's YouTube channel for more great developer tips and AEM expertise. Subscribe to be informed of our future videos. 

Do you want to talk to one of our AEM experts? We're happy to discuss a use case, business problem or any other AEM solution with you. Contact us.

Transcript

Juan Ayala: [00:04:13] my name is Juan Ayala and I'm a Technical Architect at 3|SHARE. I specialize in the Adobe Experience Manager platform. In this video, I'm going to cover error handling in AEM. This is one of the oldest topics in AEM and computer science in general. So why do I want to customize it? First, we don't want to give too much information.

Giving as little as the words "Apache sling" to attackers might give them clues about your platform. And stock traces expose way too much detail about your software.

Second, error pages should be branded and friendly. If you wind up at a page that looks like this, there's nothing to keep that user on your site.

It's a dead end.

Third, content authors should be able to make content updates. Error pages contain content, [00:05:13]sometimes different languages. It should be updatable like any other page on the site. And finally you want to look like a pro. If error pages looked like this users, aren't going to trust you. I wouldn't give you my password or credit card information.

Let's get started. For this lab, I have set up a local AEM author and publisher using the cloud SDK with Java 11. I have also extracted the dispatcher tools bundled with the SDK. It's all well-documented on the Adobe site. Here is my local author and publisher with no content, and the dispatcher tools directory.

I'm going to create a plain archetype project now, setting the AEM version to cloud.[00:06:13]

Now that I have the archetype project created an imported into IntelliJ. I'm going to create two run configurations. The first one will be so that I can deploy the entire application package onto the author instance using the auto install, single package profile. And the second one will be so that I can do the same onto the publish using the auto install, single package publish profile.

I'm going to get everything deployed onto the author instance.

And then I'm going to get everything deployed onto the publish instance.

I will need two content pages once with a 500 internal servers and the other for the 4-0-4 (404) [00:07:13] not found errors. These are simple content pages. I'm going to create them using the sample template that was created with the archetype project.

First I will create an errors landing page.

Underneath the errors page, I will create a 4-0-4 (404) page. The title can be friendly, but the name of the node must be 4 0 4.

I'm also going to create a 500 error page next to the 4-0-4 (404) page.

Next, I'm going to use a managed publication wizard to publish the error pages. Within the wizard, I will have the option to publish a tree by including all the children. The wizard replaces a classic UI tree activation wizard that is not deprecated in the cloud service.

Finally, I've verified that the error pages have been published by checking [00:08:13] C-R-X-D-E (CRXDE) and the publish instance.

Now that our content is published, I'm going to start up the local dispatcher. I'm going to open up the cache folder to keep an eye on the files to get cached. I started Dispatcher with a trace one level.

I access a page that doesn't exist. This is a default for, for response from the publisher. When I view the page that doesn't exist in the publisher, I get the same content.

This is the way the dispatcher will get the error code and content from the publisher.

The user will request a page, but dispatcher doesn't have it so it will request it from the publisher. The publisher doesn't have it. So we will return a 4-0-4 (404) with content. The dispatcher deems that it's not cachable and we'll serve it back up to the user. We are going to customize the way Sling generates the error content.

We are going to be doing this by setting up the ACS commons error page handler. [00:09:13] Based on the error code it intercepts, it will pull up the corresponding content page from the error's content path. I'm going to embed the ACS application content packages into my own deployment package.

Next I'm going to create a file to overlay the Advanced tab of the basic page template.

Then I create the files to overlay Sling's error handler scripts.

You will find the contents you need on the ACS Error Handler documentation page.[00:10:13]

The advanced folder must be a Sling folder.

We only need to define a single required field in the tab overlay. It will leverage a Sling resource merger to wedge the field into place. And finally, I update the filter XML to include the two new overlay paths.

I'm going to get everything deployed onto the author instance.

I'm going to kick off the publish instance built, and while that runs, I'm going to update the page property on the author. I open up the properties dialogue on the language group page and select the Advanced tab. This is where that tab overlay was merged. I set the path to the error pages so that any error generated under this language group will pull error content from that location.[00:11:13]

Now, when I try to access a page that doesn't exist on the author. I see the 4-0-4 (404) content. When I try the same on the publisher, I still see the default content. That's because the page property hasn't been published

All, I need to do is a quick publish on the language group page.

I verify that the page property was published.

And finally, when I try to access a page that doesn't exist, sling will send back the 4-0-4 (404) content.

We are now going to set up error handling in Apache. This is how it works.

The user will request a page, but dispatcher doesn't have it so it will request it from the publisher. The publisher doesn't have it. So we will return a 4-0-4 (404) with content[00:12:13]

This is where it gets different from the first setup. Instead of sending the 4-0-4 (404) code and content back to the user, Apache will look to see what content you should use for the current error code. It makes a request back to the publisher for the error page. The publisher responds with the error content.

It should always be an okay response. The dispatcher will now cache the content for the error code before serving it back to the user.

If the error code is ever encountered again, it will pull up the content from cache instead of making a call back to the publish.

Let's talk to the dispatcher so we can make updates to the Apache configuration

Since the default vhost is immutable. I need to create a new vhost based on the default. Now I create a symlink to enable a new vhost. I am prefixing it with [00:13:13] zero one to ensure it goes ahead of the default, vhost. The default vhost should always go last. Now that I have a vhost, I can start making updates.

First. I'm going to instruct the dispatcher module to delegate all errors to Apache. I do this by setting the dispatcher pass error parameter to one.

Now I need to tell Apache where to find the error content by using the error document directors. I am done with my Apache configuration so I'm going to start the dispatcher back up.

I load local host 8080 in the browser. Before I go any further. I notice that there is a login token cookie. when this is present, the dispatcher will that cash anything. So I'm going to open up an incognito window. When I navigate back to the page that doesn't exist, [00:14:13] I get back the 4-0-4 (404) content.

I can verify my cache directory that the 4-0-4 (404) page is now there.

And I can verify in the log that the cache actually wants to create.

I reload the browser

and now I see in the log that the cache action wants to deliver. This means it found a page in the cache and there was no call back to the publish. Although you can set up both ways of error handling, you only really need one. My personal preference is to do it in Apache. The configuration is super simple and it takes advantage of dispatcher caching.

Thanks for watching.[00:15:13]