OpenWGA 7.9 - OpenWGA Concepts and Features
Design and development » Design directories » OpenWGA system resourcesIncident designs
Incident designs are WebTML modules inside the system resources folder which are automaticallly used by OpenWGA on certain default incidents of a request to handle the response:
- HTTP Errors
- User Login
The place for these incident designs is folder /tml/html/wga/incidents and the following predefined names for WebTML modules are to be used in there:
- login.tml: When a user login form should be rendered for the current app (and there is no login page defined via publisher option) then OpenWGA will render this WebTML.
- error.tml: In case of any HTTP error OpenWGA will render this WebTML.
- error_errorcode.tml: In case of an HTTP error of the code specified as "errorcode" in the file name OpenWGA will render this WebTML, overriding an eventually present "error.tml". Specify the full three-digit error code as part "errorcode", for example "error_404.tml" for error 404. You can replace single digits with a "x" if you want to use this design, no matter what that digit is. For example: "error_4xx.tml" will be used on all error codes 400-499.
You can redirect the incident handling of one app to another using publisher option "Incident handling redirected to app". So if an incident occurs on one app where this is configured it is actually the WebTML from the design of the app you are redirecting to that is used to handle this incident.
While incidents generally are normal WebTML requests they have a special status as they are called a different way and therefor may also work a bit different than regular WebTML. Please take account of the following notes about the individual incidents and their special behaviours.
Login incidents
A login incident generally is like a contextless WebTML request to the incident module and therefor works in a quite usual way.
There are two ways to build login functionality for OpenWGA into a WebTML module:
- The legacy HTTP way:
- Create a simple HTML form, method "POST" whose "action" URL is "/login" below your OpenWGA context path
- Add HTML inputs with the following names:
- "username": The user name input field
- "password": The password input field
- "domain": Hidden field containing the name of the OpenWGA domain to login to, like "default".
- "redirect": Hidden field containing the URL to redirect to after a successful login. You are provided the original URL to which the initial user request went as URL parameter "redirect", so you can use this.
- If the login fails the user is redirected back to the login page with an URL parameter "loginerror" containing value:
- "1" for a regular failed login where the username is unknown or the password does not match
- "2" if no redirect was specified and also no referer header is available to which OpenWGA could redirect the user back. This is actually an error of the WebTML module or the call itself.
- The WebTML way:
- Create any WebTML form suitable of taking login data for your system.
- Call an WebTML action on a login attempt which will either be default action $login or a TMLScript action using method Auth.login(). Provide all login necessary data as parameters.
- On a successful login use method WGA.redirectTo() to redirect your user back to the protected resource. You are provided the original URL to which the initial user request went as URL parameter "redirect", so you can use this.
- Otherwise use the known WebTML functionalities to handle login errors.
If you redirect incident handling to another app note that the URL and therefor the WebTML request will actually go to the the incident handling app, not the app that might have been adressed in the first place. This allows you to design a WebTML login page even if the adressed app is anonymously inaccessible. In turn, your incident handling app therefor should be anonymously accessible or your login page will not be able to be rendered. Also note that the WebTML functionalities there will all work relative to the incident handling app, not the adressed app.
Error incidents
Error incidents, while they technically also are like a contextless WebTML request to the incident module, are quite special WebTML requests in that they may get rendered under any arbitrary URL which provoked the error and therefor does not match the URL that such a contextless request normally has. This has implications on any functionality that uses the current request URL to provide further functionalities:
- WebTML actions, which will not be possible to being called from an error incident page
- WebTML portlets, which will not be AJAX-refreshable on the error incident page
- Everything retrieving the current request URL, like WGA.requestURL, WGA.urlBuilder() which most likely cannot be used to build URLs for working functionalities
Therefor an error incident module should be very defensive on the functionality it provides. More precisely: It should not provide any functionality that needs to reproduce the current WebTML environment in a later request.
The error incident module receives the necessary information about the error that happened by the WGAError object that is available as WebTML variable "wgaerror".