Configuring Grid Report Templates

Overview

The Export to Report grid flow is available to create a report from search grid results in each of the search applications in CCLAS, as well as various other grid in update applications, for example, the job sample grid.

Two grid reports are 'special'—job status reports from the search results grid in the CCSTRP—Job Status Report application and financial reports from the search grid results in the CCFNRP—Financial Report application because they have additional data sources exposed to them.

Exclusion

This technical guide does not provide details on report authoring tools.

Process

Understanding the Grid Report Generation Process

Refer to the To build report templates for grid reports, an understanding is required of the report generation process.

Grid Report Generation Process

Authoring the Report Template

The Crystal Reports and Chunk Text report engines are used to create reports in CCLAS.

  • A Crystal Report template is a report template (.rpt file) that defines the report using the report file format made by Crystal Reports. These are created in the Crystal Reports template authoring tool.

  • A Chunk Text report template is a report template (.tpl file) used by the Chunk Template Engine for Java. Refer to Chunk Homepage, Documentation and Examples. These are created with a text editor.

Report Template Content

Crystal Reports

  • A single Crystal Report RPT (report template) file, or
  • A ZIP file which contains:
    • A single Crystal Report RPT file, along with the associated XSD file used to create the RPT file, which is not used to generate the report but is used in report template construction, so is included here for reference only and for further re-design of the RPT file
    • An optional RFD (report field definition) file used to limit the fields in the default result sets
    • An optional DSC (direct source connection) file used to add additional result sets
    • Optional graphics or document files that are to be included in the Crystal Report.

Chunk Reports

  • A single text TPL file, or
  • A ZIP file which contains:
    • A single text TPL file
    • An optional RFD file used to limit the fields in the default result sets
    • An optional DSC file used to add additional result sets
    • Optional graphics or document files that are to be included in the Chunk Text report.

Template File Layout

Crystal Reports—RPT file

  • The DTO (Data Transfer Object) structure is required to author the report template. For Crystal Report templates, the DTO is defined and built by the XSD file accompanying it in the Crystal Report template, and then used by the Crystal Report authoring tool to place fields into the report template.
  • The tool allows for the layout of fields as they are to appear in the physical report.
  • The report data source for those fields—The RPT is built by referring to DTO (Data Transfer Object) properties from an ADO.NET (XML) data source, where the DTO is built from the XSD (XML Source Definition) that describes the core grid report result set and any additional result sets.

Chunk Reports—TPL file

  • The DTO (Data Transfer Object) structure is required to author the report template. For Chunk Text report templates, the DTO is used as a reference to determine the nomenclature of fields placed into the report template.

  • A header line that contains the expected data sources, and must be of the following construct:

    {!-- Ventyx-Datasource-Aliases: ReportDataSource1[, ReportDataSource2[,ReportDataSource3...]]]--}

    • The report data sources are those provided to the report generation process by default, or those created by a DSC.

    • The header line MUST be specified exactly as {!-- Ventyx-Datasource-Aliases: ... --}.

      • If the header line is badly set up, for example, the Ventyx- text is missing, where:

        • No rows are selected in the search results grid, then the default search results grid data source (for example, RSJobSearch passed from the CCREGN—Job Search application) is populated with all records matching the search criteria.

        • Rows are selected in the search results grid, then the default search results grid data source is empty.

        and the DSC data sources are not populated because the template does not know to look for them.

      • If the header line is set up correctly, where:

        • No rows are selected in the search results grid, then the default search results grid data source is populated with all records matching the search criteria.

        • Rows are selected in the search results grid, then the default search results grid data source is populated only with the selected records.

        and the DSC data sources are populated where the data source names match.

    • Examples:

      • {!-- Ventyx-Datasource-Aliases: VJob, VSample, VSampleSchemeAnalyte, VSignatory, RSReportRequestSampleSchemeAnalyte--}
      • {!-- Ventyx-Datasource-Aliases: RSSampleSearch, JOBSAMPLE --}
      • {!-- Ventyx-Datasource-Aliases: RSSpecificationSchemeVersionAnalyte --}

  • Loops to work through the available report data sources.

    • A loop clause must be of the following construct:

      {.loop in $ReportDataSource1 as $DS1}
      Text text: ${DS1.Field1}
      ...
      {/loop}

    • Loops may be nested.

    • A loop counter is available for use.

    • Example:

      • {.loop in $RSSampleSearch as $S counter=$i,1}
        {.if ($i==1)}
        Lab code {$S.LaboratoryCode}
        Job name {$S.JobCode|onempty()}
        {/if}

    • An onEmpty clause can be used to trap situations in which no records are contained in the report data source.

      {.onEmpty}

      Text text

    • Examples:

      • {.loop in $JOBSAMPLE as $JS}
        {$JS.S_NAME}
         {.onEmpty}
        {/loop}
      • {.loop in $RSSpecificationSchemeVersionAnalyte as $SpecificationSchemeVersionAnalyte}
        ~~~
        Description : {$SpecificationSchemeVersionAnalyte.Description|onempty()}
        SpikeAdjustmentDescription: {$SpecificationSchemeVersionAnalyte.SpikeAdjustmentDescription|onempty()}
        ~~~
        {.onEmpty}
        No data found.
        {/loop}

  • Where a value may return empty, the onempty event can be used to supply a value.

    • Examples:

      • {$Job.FINALISED_DATE|onempty()|dtfmt(dd-MMM-yyyy HH:mm)}
      • {$SP.CLIENT_SAMPLE_NAME|onempty()|rpad(40)}

Available Data Sources

The reportable data comprises:

  • Core result set—The grid content returned from a search application, or a details grid in an update application.

  • Views constructed from the core result sets
  • Additional data sources created by a DSC zipped with the report template. A direct source connection (DSC) file is used to create result sets for the report, including database fields, logo images and text notes.

Crystal Reports

  • Core result set, views, and additional result sets.

  • When designing Crystal Report report templates with CCLAS data, in order to exclude certain attributes from the reporting XSD files, they should be added to the dtoSpecificIgnoredFields list in AbstractReportModelTransformer.groovy (cclasCore → plugin project).

Chunk Report

  • Core result set, views, and additional result sets, however, the system only builds those defined in the header line.

Grid Report Data Sources

Creating Additional Result Sets for a Grid Report

Often there is a requirement to use a custom result sets to the report. These are built using a direct source connection (DSC) file.

If a DSC file is used, it needs to be zipped with the report template and the ZIP file uploaded to CCLAS using the CCTPLR—Report Template application.

With Crystal Report and Chunk Text reports that use a DSC, there is no fixed structure of the result sets, as it depends on the SQL query that is supplied in the DSC. As such, a custom XSD or TTX file (Crystal Reports Tab Separated Text file) that matches the columns of the DSC's SQL query needs to be created in order to construct the Crystal Report template.

Note: There are some discussions online that indicate TTX is old technology, and that XML is its replacement. Being aware of TTX would be prudent, however, as there are existing templates using this format.

Structure of a DSC File for a Grid Report

Limiting Fields Included Within the Core Result Sets

Often there is a requirement to limit the fields included within the core result sets, to keep report result sets as small as possible. This is done by using a resource field definition (RFD) file.

If an RFD file is used, it needs to be zipped with the report template and the ZIP file uploaded to CCLAS using the CCTPLR—Report Template application.

An RFD file can be embedded with the following report engines:

  • Crystal Reports
  • Chunk Text
  • Other—Groovy.

Where the ZIP file includes more than one RFD file, the first randomly found one is used—therefore it is best to have only one RDF file in the ZIP file.

If the RFD file does not include a property used by the report template, then the report document has that field empty as it was not populated by the RFD.

If a property of an object is referenced without the object's code or business keys being included in the RFD, then the property are not populated.

Unix versus Windows Report Line Endings

By default, generated reports will have Unix line endings (i.e. just the newline character). If you need the report to have Windows / DOS line endings (i.e. carriage return + newline) then add the ${CR} tag to the end of each line to be generated to the TPL file. This tag will be replaced with the carriage return character during report generation. For example:

Report Template with CR tags

{!-- Ventyx-Datasource-Aliases: GRIDS,SEARCH_PARAMETERS,JOBS,RSJobSearch  --}
{.loop in $GRIDS as $DATA  }
Source,{$DATA.SOURCE:}{$CR}
{$CR}
Basic Variables{$CR}
-----------------------{$CR}
Variable,Value{$CR}
{$CR}
ORG_CODE,{$DATA.ORG_CODE:}{$CR}
LAB_CODE,{$DATA.LAB_CODE:}{$CR}
LAB_NAME,{$DATA.LAB_NAME:}{$CR}
GRIDCODE,{$DATA.GRIDCODE:}{$CR}
GRIDCODES,{$DATA.GRIDCODES:}{$CR}
LANGUAGE,{$DATA.LANGUAGE:}{$CR}
{$CR}
{$CR}
{$CR}
{.onEmpty}
No GRIDS data found.{$CR}
{/loop}
{.loop in $SEARCH_PARAMETERS as $DATA  }
Source,{$DATA.SOURCE:}{$CR}
{$CR}
Basic Variables{$CR}
Source, {$DATA.SOURCE:}{$CR}
OrganisationCode, {$DATA.ORGANISATION_CODE:}{$CR}
OrgCode, {$DATA.ORG_CODE:}{$CR}
LaboratoryCode, {$DATA.LABORATORY_CODE:}{$CR}
LabCode, {$DATA.LAB_CODE:}{$CR}
{$CR}
JOB_TYPE, {$DATA.JOB_TYPE:}{$CR}
SEARCH_SCOPE, {$DATA.SEARCH_SCOPE:}{$CR}
INSTRUMENT_CODE,{$DATA.INSTRUMENT_CODE:}{$CR}
START_FROM_01,{$DATA.START_FROM_01:}{$CR}
START_FROM_02,{$DATA.START_FROM_02:}{$CR}
START_FROM_03,{$DATA.START_FROM_03:}{$CR}
{$CR}
{.onEmpty}
No SEARCH_PARAMETERS data found.{$CR}
{/loop}

Examples

Reporting Scripts

Based on either a laboratory-wide reporting script or a script linked to the specific report template, the system may be customised to run reporting event script are various points throughout the report generation process. These script event can be used to:

  • Construct other report classes

  • Change the exposed report classes

  • Change the template or report engine properties

  • Save the generated report documents to nominated folders

  • Print the generated report documents

  • Email the generated report documents.

Refer to the CCLAS 6 Customisation Guide for more details.

Uploading a Grid Report Template

After the report template is created, it is uploaded to CCLAS using the CCTPLR—Report Template application.

Note: If the file name is not unique, that is, a file already exists in the report repository with the same name, then there can be issues downloading the file that you think you have created.

Upload a grid report template

Making a Grid Report Template Available for Grid Reports

Application preferences for grid reporting control which report templates are available from a particular grid, based on the particular type of object.

If the SEARCH_REPORT_<ApplicationName> application preference is defined and contains a comma-separated list of report templates, in the format Report Template Code:Text Description, when a grid report is requested, then the Report Template Code drop-down list is populated from this list where the report template is active. Note that the system still looks for preferences based on the base application name even where screen personalisations are in place.

Make a grid report template available for grid export

Note: Where a desired grid report template is not included in the available list, its code can still be entered into the selection box.

Setting a Printer and an Email To Address for Distributing Grid Reports

If print details were entered then the grid report document is printed to the selected printer device.

If email details were entered then the grid report document is emailed to the email addresses supplied.

If the SEARCH_REPORT_DEVICE application preference is defined and contains a Device Code, and no default device is attached to the report template in use, when distribution details are entered for a grid report, then the Printer defaults to this device.

If the SEARCH_REPORT_EMAIL_TO application preference is defined and contains a valid email address, when an email is generated for a grid report, then the Email To email address is set to this email address.

If the SEARCH_REPORT_EMAIL_SUBJECT_TEXT application preference is defined and contains a syntax code, and a syntax exists with that code and a Syntax Type of Report Request, when an email is generated for a grid report, then the email subject contains the text generated by the syntax.

If the SEARCH_REPORT_EMAIL_MESSAGE_TEXT application preference is defined and contains a syntax code, and a syntax exists with that code and a Syntax Type of Report Request, when an email is generated for a grid report, then the email message body contains the text generated by the syntax.

Configuring the Language of a Grid Report

If the EXPORT_REPORT_LANGUAGE application preference is defined and contains a Language, when a grid report is generated, then the Language defaults to this language. If this preference is not defined, or is defined and contains an invalid language, when a grid report is generated, then the Language defaults to EN_AU.

Configuring the Batch Queue for Grid Report Generation

The system batch queue is used to perform the any necessary distribution of the reports. Refer to Set the BATCH_QUEUE_TASK_PRIORITY Preference.