Document toolboxDocument toolbox

(2022.1) Crystal Development

Owned by Pete Stapley (Deactivated)
Jan 08, 2024

Crystal Reports Development for PCR-360

This page describes expectations and guidelines for developing powerful Crystal Reports designs that utilize the dynamic & flexible interface of PCR-360.

Prerequisites

This page assumes that you:

  1. Have a valid license to the SAP Crystal Reports program (version 14+ is strongly recommended, as older RPT formats are untested and may not run correctly)
  2. Know the Crystal Reports Designer program and how to construct reports
  3. Know how to create data connections from your Windows machine to the PCR-360 database using drivers appropriate to the platform your institution uses for PCR-360
    • Note: Hosted clients who request/require direct access to the database are provided connection information, which can be used for this purpose.
  4. Know how to generate database objects you may need for your report (views, auxiliary tables, etc.)

Baseline Expectations

The Java-based toolkit we use for importing and running reports allows us to provide this feature on Linux servers and provides a broad range of common functionality for Crystal reports, but it does have some drawbacks.

  1. Our capability to import information about a report file is gradually improving, but there are some limitations due to the Java toolkit provided by SAP. We don't run Crystal Server, nor a Java web-service like Apache's Tomcat. If you discover some feature of Crystal isn't working at all when the report is run from our system, we're happy to discuss it and determine our capability to support that feature in future updates.
  2. We can offer support and troubleshooting in report design and integration in PCR-360, limited to the application requirements and best practices necessary in the report creation process.
  3. Font rendering in particular can be best described as "quirky". We recommend using common, ubiquitous fonts (Arial, Times, Courier, etc.) for best compatibility between the Windows design environment and the Linux/Java run-time environment. Since the RPT file is designed in Windows, you have access to any font your Windows system provides. However, many of those are proprietary, specific to Windows, or otherwise are unavailable for Linux. For clients who host PCR-360, if your system administrator wishes to install additional fonts to the server PCR-360 runs from, we cannot ensure they'll work when Java renders the reports.

Import Capabilities

When a RPT file is uploaded to PCR-360, several pieces of information are read from the file and stored to the database. This data is used for presentation of the report when it's run.

In Crystal, go to File > Report Summary Info:

Retained fields: Author, Comments, Title, Subject

Parameters are read as they are defined and ordered in the Field Explorer:

Field Explorer > Parameter Fields

The import process can determine most properties of each Parameter, and we detect some additional information to decide how the Parameter should be treated when asking for input at run-time:

  1. Boolean Parameters
    • Those with no Descriptions set for True/False will be presented as a Checkbox input. You can change this to drop-down and add descriptions for TRUE/FALSE after import if desired.
    • Those with Descriptions set will be a drop-down input. This setting cannot be changed.
    • You can edit the Descriptions in the application after import. However, the Values column must always have exactly 2 rows: 1 "TRUE" and 1 "FALSE" (case-sensitive).
  2. Number Parameters
    Most Number parameters will be left as-is, but you can use some special patterns in the Parameter name to alert the import process to treat it differently.
    • You can set a specific Picker element for a Parameter using this pattern:
      anyNameYouWant_somethingPicker_RECID
      The last portion of the parameter name is key here: It must end with "_RECID", preceded by a valid Picker key name. Refer to the Reference Key column here: Picker Field. Segments of the parameter name must be underscore-separated for the import to detect each piece.
      Example: anyNameYouWant_contactPicker_RECID will be represented as a Contact Picker when you go to run the report.
    • You can manually select a Picker for the parameter after import if you wish. However, if the Picker is automatically detected as described above, it cannot be changed.
    • Anything not matching pattern(s) described above will be represented as a generic text input, but data entry will be limited to numeric values (including negative and decimals).
  3. Date/Time/DateTime Parameters
    • These three types will be represented with Date/Time pickers. The form Element selection for these cannot be changed.
  4. String Parameters
    • Be cautious about mixing Optional Prompt with Min Value (length) settings. See Known Issues below.

IMPORTANT NOTE: Parameters must contain only alphanumeric and underscore characters. Keep in mind the Prompt Text is what your users will see for the input, not the parameter name. The Prompt Text can be adjusted from the Parameter Maintenance Form:

Parameter Maintenance Form

Development Guidelines

Database

PCR-360 doesn't use the data connection you set up in the report to connect to data sources. It ignores those, using settings from the application itself to connect only to the PCR-360 database. This means you cannot effectively use multiple data sources, nor use a parallel database that reads data from PCR-360. If you host 360, you may add Views to the database to collect data as needed. While Crystal Reports does support execution of Procedures, we don't recommend this practice. Stored Procedures can be used to modify data while also collecting data for the report. If data is modified outside the application, it may cause negative side-effects such as missing required data, unreadable records, incorrect validations, etc.

Sub-Reports

Sub-Reports are a good way to present disparate sets of data that share a common data point (for instance, viewing aggregated Labor, Equipment, and Miscellaneous Charges on a Service Order). However, when Parameters are imported, the process currently cannot read through sub-reports to import any Parameters they have, nor determine how the sub-report is linked to the parent.

Typically, sub-reports are linked using data from the parent's query results being passed to the child to feed a parameter. The connection is invisible to a user. However, if a sub-report parameter needs to be presented for input, the import process will miss it. For these cases, a parameter needs to exist on the parent that is linked to the sub-report's parameter.

In this sample report, the sub-report has been opened in design mode by double-clicking the sub-report object in the parent. It's visible as a new tab next to the "Design" tab of the parent. We see the sub-report has a Parameter called SubReportStringParam. We want to create a parent-level Parameter that will ask for user input and feed it to the subreport's Parameter.

Sub-report Design mode showing Parameter

Set up the parent's Parameter. Match the specification needed to meet the sub-report's Parameter.

Parent report's Field Explorer Parameters

Next, set the link from the parent report to the sub-report. Right-click the sub-report and choose "Change Subreport Links...":

Sub-report menu from parent

In the Link window, select the Parameter from the parent into the "Field(s) to link to" box, then choose the existing Parameter in the sub-report it should feed data to. Be careful not to generate a new parameter (typically prefixed with "?Pm-" and the name of the parent's Parameter).

Sub-report Parameter Link Setup

Known Issues

We are continually working to improve the interaction between our web-based application and Crystal Reports, but there are some challenges we have yet to overcome.

  • String Parameters cannot combine Min Value (length) of 1+ AND Optional Prompt _TRUE_. Generally, "Optional Prompt" is interpreted as "optional value", but if no value is submitted, an empty string "" is used to ensure the Parameter actually reaches the report. Since "" is a 0-length value, it won't meet the 1+ minimum length requirement, and the report will fail. String Parameters with a Min Value will automatically be set as Required for the parameter form and this setting should not be changed.
  • Edit Masks are also not yet utilized on the Parameters form. The information is imported, however. and utilization will be improved in an upcoming release. Parameters with an Edit Mask defined will be set as Required and this setting should not be changed.
  • Min/Max String-length or Numeric-value traits on Parameters are not yet utilized on the Parameters form. The information is imported, however, and utilization will be improved in an upcoming release.
  • Sub-Report Parameters are not imported, nor is any linking information detected. See Sub-Reports section to work around this.
  • Report failure due to input not meeting Parameter restrictions is currently not reported to the user. Only a "Failed to run report" message is displayed. We hope to improve the feedback system to provide more informative failure messages in an upcoming release.
  • Fonts:
    • Using uncommon fonts from Windows may result in unexpected rendering of the PDF. Reports are run from Linux servers, so some Windows fonts aren't available. You may see (at best) improperly rendered fonts, or (at worst) garbled text or none at all. We recommend commonplace, generic fonts: Arial, Courier, Times (and Times New Roman), etc.
    • Avoid mixing fonts within a single text object. This has been shown to cause rendering issues and is considered unreliable.