Create a JSP Page Document Template
DEPRECATED: A JSP page can no longer be used as the basis for a document template, due to limitations on the number of contexts in which they can be successfully used.
Background:
- JSP pages need to be compiled and generated in a scheduled background process. But the background processes have no concept of a session, while a session identifier is required when sending an email to ensure that the message goes out with the intended attachments. So it is not possible to send an email attachment when the document template is based on a JSP page, whether in a Rule, a Process, or one of the Java sendEmail APIs.
Suggested Alternative: Use an HTML Document Template.
- Wherever possible: In place of Java code, use Velocity code for loops and conditionals.
- When necessary: Use Java code to create a Document Template Class, and use that class to provide the data that the template processes.
Best Practice:
Identify existing document templates that are based on JSP pages, so designers know to avoid them in the contexts listed above. For example, add the word "JSP" to the template name. (That practice also helps to identify document templates that need to be converted.)
A JSP page can be used as a Document Template.
Working with a JSP Page
Creating the Template Page
- Start by creating a JSP/Html Page in the platform.
- Turn off the Include Headers option for that page.
- (Those headers contain platform-specific Javascript that interfere with template processing.)
- Edit the page either in the platform, or using the Eclipse Plug-In.
- Add boilerplate text and fixed graphics
- Use JSP code and the platform APIs to control page content, as explained below.
Accessing Record Information
When a JSP Page is launched from a context that is associated with a particular object record, the request object available in the JSP page contains the identifiers needed to obtain additional information from the record, using either the REST record Resource or the Java record handling APIs.
To get all of the parameters available in the request object, and their values:
- <syntaxhighlight lang="java" enclose="div">
<%
String[] params = request.getParameterValues();
for (int i=0; i<params.length; i++)
{
String paramName = params[i];
String paramValue = request.getParameter( paramName );
}
%> </syntaxhighlight>
To obtain a record identifier from a request object sent by the platform:
- With the object ID and record ID, use the getRecord API to retrieve the record.
- <syntaxhighlight lang="java" enclose="div">
<%
String object_id = request.getParameter("object_id");
String record_id = request.getParameter("record_id");
%> </syntaxhighlight>
Note: Although the object_id is alphanumeric, it can be used in any API that requires an object name.
To obtain a record identifier from a request object sent by a Custom Action button:
- This code gets the record IDs and uses the searchRecords API to retrieve the records:
- <syntaxhighlight lang="java" enclose="div">
<%
// Get the object ID and the comma separated list of record IDs
String object_id = request.getParameter("object_id");
String selectedRecords = request.getParameter("selectedRecords");
// Break the comma-separated list into record IDs.
// Join them with "OR" operands for use when searching for the records
String filterCriteria = "";
if (selectedRecords != null)
{
StringTokenizer st = new StringTokenizer(selectedRecords,",");
while (st.hasMoreTokens())
{
if ( !"".equals(filterCriteria.trim()))
{
// Criteria string isn't empty, and we're adding another expression
// Prefix the new expression with a boolean OR operator
filterCriteria += " OR "
}
filterCriteria += "record_id = "+ st.nextToken();
}
}
// Use the filter criteria to fetch the selected records
// Here, we ask for the record_id and name fields
Result results;
results = Functions.searchRecords(object_id , "record_id,name", filterCriteria);
int resultCode = results.getCode();
if (resultCode < 0)
{
// Error occurred
}
else if (resultCode == 0)
{
// No records found. (This situation should never occur.)
}
else
{
// Records retrieved successfully
// Process them here
ParametersIterator iterator = results.getIterator();
while(iterator.hasNext())
{
Parameters params = iterator.next();
String recordID = params.get("record_id");
String recordName = params.get("name");
// Take additional action according to your business logic
}
}
%> </syntaxhighlight>
Processing Related Records
Use the Java searchRecords API on the Related Object, selecting all records whose lookup-field value matches the current record ID.
For example, when the ClaimItems object has a lookup to Claims. When processing a Claim with record ID 1234, search for ClaimItems records who have claim lookup field with that value.
Using APIs
In general, the Java APIs and REST APIs provide equivalent functionality. But there are some differences, as well. So while the Java APIs are generally more convenient to use in a JSP page, you may also want to review the functionality listed in the REST API CheatSheet.
The following Java API classes are implicitly imported into JSP Pages:
Other considerations:
- You cannot make a database connection. (Use the Java Record Handling APIs, instead.)
- The maximum number of loop iterations, along with other restrictions, is determined by the configuration of the platform Governors.)