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! ..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.

<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>

<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 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 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 Description:Email
View Details Hide 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 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.

| 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
| Action Class: EmailComponent
| Action Desc: Email
| Loop Index: 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)

Browser not supported