Configuring custom error pages with Oracle REST Data Services

If you need to configure a custom error page instead of the error page generated by Oracle REST Data Services (ORDS), then do the following:

  • Edit the defaults.xml file in the ORDS configuration folder
  • Add the following setting to defaults.xml:

    <entry key="error.externalPath">/path/to/error/pages/folder/</entry>
  • /path/to/error/pages/folder is the fully qualified path to a folder which contains files named with the following pattern {status}.html, where {status} is the HTTP status code that you wish to define a custom error page for.
  • For example if you wish to define a custom error page for the HTTP 404 – Not Found status and store it in a folder named /usr/local/share/ords/error-pages/ then create a file named 404.html in /usr/local/share/ords/error-pages/ and configure error.externalPath to point at /usr/local/share/ords/errro-pages/.

Understanding the Oracle REST Data Services Configuration Folder

Oracle REST Data Services (ORDS) needs a location to store it’s configuration files. The location is configured using the config.dir setting. You can view and set this setting using the configdir command.

Set config.dir setting

$ java -jar ords.war configdir /tmp/wls/conf
Feb 27, 2014 2:58:47 PM oracle.dbtools.cmdline.ModifyConfigDir execute
INFO: Set config.dir to /tmp/wls/conf in: /Users/cdivilly/ords.war

View config.dir setting

$ java -jar ords.war configdir
Feb 27, 2014 3:00:16 PM oracle.dbtools.cmdline.ModifyConfigDir execute
INFO: The config.dir value is /tmp/wls/conf

The important thing to be aware of is that the configuration data is not stored directly in the location pointed to by config.dir. Instead the data is located in a sub-folder named after the context-path (aka context-root) that ords.war is deployed at.

A second point to be aware of is that when configuring ORDS, the context-path that the application will be deloyed at is not known, so it is inferred from the filename of ords.war.

Deploying to /apex

If you need to deploy ORDS to a context-path of: /apex, then make sure to do the following:

  1. Rename ords.war to apex.war
  2. Configure ORDS by doing:
    java -jar apex.war
  3. Deploy apex.war to your application server

If you follow these steps in the order laid out above, you will not encounter any issues.

Help! I forgot to rename ords.war before configuring and deploying it

If you did not rename ords.war before doing configuration and deployment, then you are likely to see an error page like the following:

ORDS Not Configured

ORDS Not Configured

Note the highlighted text in the bottom left. This reveals the problem, ORDS is expecting to find the configuration files in /tmp/wls/conf/apex (because the context-path is /apex), but does not find anything in this folder, because the data is actually in /tmp/wls/conf/ords.

In this case, to address the problem rename or copy /tmp/wls/conf/ords to /tmp/wls/conf/apex, and restart ORDS.