Custom Pages

The IBM Application Gateway (IAG) under certain conditions will return server generated responses. These conditions include scenarios such as error conditions or server generated operations.

By default, IAG includes a set of unbranded responses which will be served. A copy of the default responses are can be retrieved from the pages directory of the IAG Resources repository.

PagesDescription
management_pages.zipThis zip file contains a directory structure including the default management responses.
error_pages.zipThis zip file contains a directory structure including the default error message responses.

Replacing the default Response Pages

Server generated responses can be customized by providing a set of response templates in the directory structure expected by IAG. The content can either be provided as a zip archive or a directory which is bind mounted into the IAG container.

For example, to replace the default error responses with the content of an archive errorPages.zip which is mounted in the container at /var/iag/config/errorPages.zip:

server:
  error_pages:
    content: "@errorPages.zip"
    type:    zip

See also: YAML Reference for error_pages

For example, to replace the default management responses with the content of the directory myMgmtPages which is mounted in the container at /var/iag/config/myMgmtPages:

server:
  management_pages:
    content: myMgmtPages
    type:    path

See also: YAML Reference for management_pages

Note that if custom responses are provided, IAG will not use any responses from the default set of responses. That is, if a custom set of responses is provided it is expected to include all possible responses you wish for IAG to serve. For this reason, the strategy recommended when customizing responses is to begin with the archive of default responses and make additions/omissions as required.

Directory Structure and Naming Convention for Management and Error Responses

The template content for Management and Error responses is expected in a specific directory structure adhering to the following name convention.

📘

Note

Note that the token <response_code> is optional for both management and error pages.

Management Pages

<language_code>/<page_name>.<response_code>.<mime_type>

Example

./C/help.html
./C/login_success.html
./C/logout.html
./C/oidc_fragment.html
./C/ratelimit.html
./C/redirect.html
./C/temp_cache_response.html
./cs/help.html
./cs/login_success.html
...

Error Pages

<language_code>/<error_code>.<response_code>.<mime_type>

Example

./C/38cf0420.html
./C/38cf0421.html
./C/38cf0427.html
./C/38cf0428.html
./C/38cf04c6.html
./C/38cf04d7.html
./C/38cf08cc.html
./C/default.400.html
./cs/38cf0420.html
./cs/38cf0421.html
...

Controlling Language Support with language_code

The default set of responses are provided in 14 different languages. When creating the directory structure, directories for languages you do not wish to serve can be omitted.

IAG will select the language for the response using the following logic:

  1. If a client indicates a particular language and a response exists for that language, it will be served.
  2. If a client indicates a particular language and a response does not exist for that language, IAG will select a response using the container language (set via the LANG environment variable)

The complete list of languages supported by IAG and their corresponding language_code values are listed below.

language_codeLanguage
CEnglish
csCzech
deGerman
esSpanish
frFrench
huHungarian
itItalian
jaJapanese
koKorean
plPolish
ptBrazilian Portuguese
ruRussian
zh_CNChinese (Simplified)
zh_TWChinese (Traditional)

Example

Consider a scenario where your application is being deployed for Canadian users and you want to only ever return English or French server generated responses.

To only ever return responses in English or French with all other languages falling back to English:

  1. Include only the C and fr directories in the directory structures for your management and error responses
  2. Run the container with LANG=C to indicate that English is the default language

Customizing HTTP Status Codes with response_code

The HTTP status code returned for management and error responses can be customized on a per-response template basis. This token of the filename in the naming conventions is optional, if a response_code is not explicitly indicated, the default value will be used.

Management Responses

The default HTTP status code for management responses is 200.

Error Responses

The default HTTP status codes for error responses vary based on the type of error. The default status codes for the standard set of error responses are:

error_codeDefault response_codeDescription
38cf0420301Moved Permanently
38cf0421302Moved Temporarily
38cf0427403Forbidden
38cf0428404Not Found
38cf04c6500Server Not Responding
38cf04d7500Server Not Responding
38cf08cc403Forbidden (Time based)
default400Any other error code

Customizing Responses for Different Types of Clients with mime_type

IAG can serve different responses based on the MIME sub-type found in the request.

For example:

  1. A web browser which presents an accept: text/html header will receive the html response
  2. An API client presenting accept: application/json will receive a json response - provided that a json response template exists in the directory structure.

IAG uses the following logic to determine the appropriate type of response to return:

  1. The MIME sub-type in the accept HTTP header of the request is inspected.
    IAG uses the first MIME entry that is found in the ‘accept’ header, disregarding
    any specified quality factor and any subsequent MIME types.
  2. If the ‘accept’ HTTP header is not present, the MIME sub-type from the
    ‘content-type’ HTTP header in the request is used.
  3. If none of the above correspond to a response template file, the default
    (html) is selected.

Example

For example, consider an environment with the following error responses:

C/38cf0428.404.html
C/38cf0428.400.json

Three different clients make a request for a resource which does not exist, this would result in the error_code 38cf0428.

Web browser client

GET /unknownResource HTTP/1.1
host: demo.ibm-app-gw.com
accept: text/html
content-type: text/html; charset=UTF-8
user-agent: mozilla/5.0 ...

In this case, the accept header is present and contains the mime sub-type html.

IAG will serve C/38cf0428.404.html to the client with a HTTP status code 404.

API client

PUT /unknownResource HTTP/1.1
host: demo.ibm-app-gw.com
content-type: application/json; charset=UTF-8
user-agent: mobile-app-demo/1.3

In this case, the accept header is not present, but a content-type header is and contains the mime sub-type json.

IAG will serve C/38cf0428.400.json to the client with a HTTP status code 400.

Other client

GET /unknownResource HTTP/1.1
host: demo.ibm-app-gw.com
user-agent: curl/7.64.1
accept: */*

In this case, both the accept and content-type headers do not contain a meaningful mime sub-type, so IAG will fall back to the html page.

IAG will serve C/38cf0428.404.html to the client with a HTTP status code 404.

Management Pages page_name

IAG provides default HTML responses for all management pages.

A complete list of the possible page_name values and details about the provided default responses is below:

page_nameresponse_codemime_type
help200 (default)html
login_success200 (default)html
logout200 (default)html
oidc_fragment200 (default)html
ratelimit200 (default)html
redirect200 (default)html
temp_cache_response200 (default)html

Error Pages error_code

IAG provides HTML responses for common error_code values and a HTML and JSON default error response:

error_coderesponse_codeDescriptionmime_type
38cf0420301 (default)Moved Permanentlyhtml
38cf0421302 (default)Moved Temporarilyhtml
38cf0427403 (default)Forbiddenhtml
38cf0428404 (default)Not Foundhtml
38cf04c6500 (default)Server Not Respondinghtml
38cf04d7500 (default)Server Not Respondinghtml
38cf08cc403 (default)Forbidden (Time based)html
default400Any other error codehtml
default400Any other error codejson

The error_code default indicates a template that will be selected for any error_code which does not have an explicitly defined response template.

Responses can be added for error_code values not listed in the default set of responses. To customize the response for an error_code not present in the default set of responses, simply create a new response file following the naming convention and including the actual error_code in the filename.

Response Macros

Contextual data can be inserted into response templates using the following macros. These macros can be used regardless of the mime sub-type.

MacroExampleDescription
%BACK_URL%https://demo.ibm.comSubstitutes the value of the referer header from the request, or "/" if none.
%CREDATTR{name}%%CREDATTR{UID}% == 502HB8S9Q1The value of the user credential attribute that has the specified name.
%ERROR_CODE%0x38cf0421The numeric value of the error code.
%ERROR_TEXT%Moved TemporarilyThe text associated with an error code in the message catalog.
%HOSTNAME%ibm-app-gw.ibm.comFully qualified host name.
%HTTPHDR{header}%%HTTPHEADER{HOST}% == ibm-app-gw.ibm.comUsed to include the contents of a specified HTTP header. If the specified HTTP header does not exist within the request, the macro will contain the text: Unknown.
%HTTPS_BASE%https://ibm-app-gw.ibm.com:8443Base HTTPS URL of the server, "https://host:port/".
%LOCATION%https://ibm-app-gateway/application1/Contains the URL to which the client is being redirected. Sent only in redirects.
%METHOD%GETThe HTTP method requested by the client.
%REFERER%https://demo.ibm.com/dispatch?foo=barThe value of the HTTP referer header from the request, or Unknown, if none.
%REFERER_ENCODED%https://demo.ibm.com/dispatch%3Ffoo%3DbarA URI encoded version of the HTTP referer header.
%URL%/application1/demo?foo=barA URI encoded version of the URI.
%URL_ENCODED%/application1/demo%3Ffoo%3DbarA URI encoded version of the URI.
%USERNAME%502HB8S9Q1The name of the user who originated the request.

Example

Consider the default error response, C/default.400.json, which contains the following content:

{
  "error_code":"%ERROR_CODE%",
  "error_message":"%ERROR_TEXT%"
}

A request is made which results in IAG needing to redirect the client. When this error response is served to the client, the %ERROR_CODE% and %ERROR_TEXT% macros are populated:

{
  "error_code":"0x38cf0421",
  "error_message":"Moved Temporarily"
}

Did this page help you?