A new feature as of BI Platform 3.6 is template error pages. There used to be no easy way to configure an error page resulting from an action sequence execution from the ViewAction servlet. We used to direct customers to create their own (Java code) MessageFormatter class if they want to customize the way the error appears to end users. This is overkill for simple customization and happily this is no longer the case. The error used to be ugly, plain and quite uniformative. The uninformative messages "Action Sequence Failed" is affectionately known as the SBC, or "something broke cap'n" error. As of 3.6 you no longer are stuck with the SBC error when something goes wrong with your action sequence! You ..and you can completely customize the way users see xaction errors using plain old html.
Extensive changes took place in the internals of the platform to render lots of detail about xaction failures. These details are now exposed in the templated error page mentioned above, but also in the pentaho.log file (as well as your appserver's log file, e.g. catalina.out).
Customizing your Error Page
To customize your error response page, open up the file "viewActionErrorTemplate.html" in your <solutions dir>/system/ui/templates folder. Any time an action sequence fails and a message formatter is applied (this happens in PUC, for example), then the message formatter system will load that template html page and replace all the tokens listed in the next section with the appropriate text. That text may be a label in which case the source of the text is a message properties file, or the text may be actual data pertinent to the error. See the next section for all the tokens that you can use in your template file. NOTE: You are not required to use any tokens at all if you do not wish. The html file you use can be as lean or as rich with messages as you wish; you have full control over the error page.
Catalog of data tokens
These tokens are used in your html error template file.
Token | Description | Message bundle key (start with "MessageFormatter.") | |
|---|---|---|---|
%ERROR_HEADING% | e.g. "The Pentaho BI Platform reported an error while running an action sequence" | RESPONSE_ERROR_HEADING | |
%EXCEPTION_MSG_LABEL% | e.g. "Error Message:" | RESPONSE_EXCEPTION_MSG_LABEL | |
%EXCEPTION_MSG% | prints the topmost exception message text | N/A | |
%EXCEPTION_TIME_LABEL% | e.g. "Error Time:" | RESPONSE_EXCEPTION_TIME_LABEL | |
%EXCEPTION_TIME% | the time the root cause exception occurred. Uses LocalHelper to format the date. | N/A | |
%EXCEPTION_TYPE_LABEL% | e.g. "Error Type:" | RESPONSE_EXCEPTION_TYPE_LABEL | |
%EXCEPTION_TYPE% |
| the actual type of the topmost Java exception | N/A |
%SESSION_ID_LABEL% | e.g. "Session ID:" | RESPONSE_EXCEPTION_SESSION_ID_LABEL | |
%SESSION_ID% |
| the name given to the session that accompanied the A.S. execution | N/A |
%INSTANCE_ID_LABEL% | e.g. "Instance ID:" | RESPONSE_EXCEPTION_INSTANCE_ID_LABEL | |
%INSTANCE_ID% |
| the unique identifier for the runtime session that executed the A.S. | N/A |
%ACTION_SEQUENCE_LABEL% | e.g. "Action Sequence" | RESPONSE_EXCEPTION_ACTION_SEQUENCE_LABEL | |
%ACTION_SEQUENCE% |
| the name of the xaction file that failed | N/A |
%ACTION_SEQUENCE_EXECUTION_STACK_LABEL% | e.g. "Execution Stack:" | RESPONSE_EXCEPTION_ACTION_SEQUENCE_EXECUTION_STACK_LABEL | |
%ACTION_SEQUENCE_EXECUTION_STACK% | a pointer into the place in the xaction file's DOM where the error occurred | N/A | |
%ACTION_CLASS_LABEL% | e.g. "Action Class:" | RESPONSE_EXCEPTION_ACTION_CLASS_LABEL | |
%ACTION_CLASS% | the name of the component or action that failed (as described in the xaction file) | N/A | |
%ACTION_DESC_LABEL% | e.g. "Action Desc:" | RESPONSE_EXCEPTION_ACTION_DESC_LABEL | |
%ACTION_DESC% |
| if the xaction provides an "action-type" element, that descriptive text goes here | N/A |
%STEP_NUM_LABEL% | TBD | RESPONSE_EXCEPTION_STEP_NUM_LABEL | |
%STEP_NUM% | TBD |
| |
%STACK_TRACE_LABEL% | e.g. "Stack Trace:" | RESPONSE_EXCEPTION_STACK_TRACE_LABEL | |
%STACK_TRACE% |
| the full Java stack trace text (can be several dozen lines long) | N/A |
%EXCEPTION_MESSAGES_LABEL% | e.g. "Possible Causes:" | RESPONSE_EXCEPTION_MESSAGES_LABEL | |
%EXCEPTION_MESSAGES% |
| an inverted (root cause first) summary of the exceptions that occurred for quicker identification of the root problem | N/A |
%SERVER_INFO% | the version of the BI Platform and other identifying information | USER_SERVER_VERSION |
Example html error template file
Here is an example viewActionErrorTemplate.html file.
| Code Block | ||||
|---|---|---|---|---|
| ||||
<html><head><title></title><link rel="stylesheet" type="text/css" href="/pentaho-style/active/default.css"></head> <body> <div id="errorResponse"> <div class="error"> <h1>%ERROR_HEADING%</h1> <div class="summary"> <div class="item"><span class="label">%EXCEPTION_MESSAGES_LABEL%</span><pre>%EXCEPTION_MESSAGES%</pre></div> <div class="item"><span class="label">%ACTION_SEQUENCE_LABEL%</span>%ACTION_SEQUENCE%</div> <div class="item"><span class="label">%ACTION_SEQUENCE_EXECUTION_STACK_LABEL%</span><pre>%ACTION_SEQUENCE_EXECUTION_STACK%</pre></div> <div class="item"><span class="label">%LOOP_INDEX_LABEL%</span>%LOOP_INDEX%</div> <div class="item"><span class="label">%EXCEPTION_TIME_LABEL%</span>%EXCEPTION_TIME%</div> <div class="item"><span class="label">%EXCEPTION_TYPE_LABEL%</span>%EXCEPTION_TYPE%</div> <div class="item"><span class="label">%SESSION_ID_LABEL%</span>%SESSION_ID%</div> <div class="item"><span class="label">%INSTANCE_ID_LABEL%</span>%INSTANCE_ID%</div> <div class="item"><span class="label">%ACTION_CLASS_LABEL%</span>%ACTION_CLASS%</div> <div class="item"><span class="label">%ACTION_DESC_LABEL%</span>%ACTION_DESC%</div> <!-- <div class="item"><span class="label">%STEP_NUM_LABEL%</span>%STEP_NUM%</div> --> </div> <div id="details" class="details"><span class="label">%STACK_TRACE_LABEL%</span><pre class="stackTrace">%STACK_TRACE%<pre></div> </div> </div> <div class="errorResponseFooter">%SERVER_INFO%</div> </body> </html> |
Example
...
Html Output text after tokens replaced
Here is an example of an action sequence failure as depicted in the log file:
...
in a ViewAction servlet response (like you would see in the Pentaho User Console). Of course, this text would be formatted and colored differently if it were actually rendered in PUC.
| No Format |
|---|
The Pentaho BI Platform reported an error while running an action sequence Possible Causes: ActionValidationException: RuntimeContext.ERROR_0035 - Action validation failed. Action Sequence: BurstSales.xaction | Execution Stack: EXECUTING ACTION: Email (EmailComponent) in IF STATEMENT: queryResult.getRowCount()>0 in LOOP ON: employeeList | Loop Index:N/A Error Time:Tuesday, November 3, 2009 4:43:47 PM EST Error Type:ActionValidationException Session ID:joe Instance Id:f77d2238-c8c1-11de-92b0-3dd9e4293f91 Action Class: EmailComponent | Action DescDescription: Email |View LoopDetails Index: N/AHide Details Stack Trace: org.pentaho.platform.api.engine.ActionValidationException: RuntimeContext.ERROR_0035 - Action validation failed. at org.pentaho.platform.engine.services.runtime.RuntimeContext.validateComponents(RuntimeContext.java:573) at org.pentaho.platform.engine.services.runtime.RuntimeContext.validateComponents(RuntimeContext.java:521) at org.pentaho.platform.engine.services.runtime.RuntimeContext.validateComponents(RuntimeContext.java:521) |
Action Sequence Failure Logging
Here is an example of an action sequence failure as depicted in a ViewAction servlet response (like you would see in the Pentaho User Console). Of course, this text would be formatted and colored differently if it were actually rendered in PUC.
...
the log file. Like the html output, the messages displayed can be internationalized through the "MessageFormatter" message bundle (see the message starting with "LOG"). However, the data printed in the log is not as easily customizable. The PentahoMessenger.java class (Java code) is responsible for the content of the error log message.
| No Format |
|---|
| Error Time: Tuesday, November 3, 2009 4:43:47 PM EST | Session ID: joe | Instance Id: f77d2238-c8c1-11de-92b0-3dd9e4293f91 | Action Sequence: BurstSales.xaction | Execution Stack: EXECUTING ACTION: Email (EmailComponent) in IF STATEMENT: queryResult.getRowCount()>0 in LOOP ON: employeeList | LoopAction IndexClass:N/A Error Time:Tuesday, November 3, 2009 4:43:47 PM EST Error Type:ActionValidationException Session ID:joe Instance Id:f77d2238-c8c1-11de-92b0-3dd9e4293f91EmailComponent | Action ClassDesc:EmailComponent Action Description:Email View| DetailsLoop Hide DetailsIndex: N/A Stack Trace: org.pentaho.platform.api.engine.ActionValidationException: RuntimeContext.ERROR_0035 - Action validation failed. at org.pentaho.platform.engine.services.runtime.RuntimeContext.validateComponents(RuntimeContext.java:573) at org.pentaho.platform.engine.services.runtime.RuntimeContext.validateComponents(RuntimeContext.java:521) at org.pentaho.platform.engine.services.runtime.RuntimeContext.validateComponents(RuntimeContext.java:521) |