Generating Reports from Report Requests

Overview

Report generation can occur once the report request's jobs, samples, tests and reports are configured.

Report Templates

The report template linked to the report request report must be configured for reports to be generated. Report templates for certificate reports must take into consideration the mandatory fields required for templates. These are:

  • Report Template Code—The unique code to be applied to the new paperwork template.
  • Type—The type of report template. For certificate reports, it must be a report template with a Type of 01—Certificate.
  • File—The source file for the reporting template. This needs to be uploaded, and the record change submitted.
  • Report Engine—The report engine that is used to generate the report.
  • Default Output Format—The file format of the generated report (text, PDF and so on), and is dependent upon the selected report engine.
  • Output File Name or Output File Name Syntax—One or both of these properties should be set for reporting. Refer to Maintaining Syntaxes.
  • A report template must be active for it to be selected for use.

Refer to Maintaining Report Templates.

Process

Paperwork and labels can be generated report requests

Generate job paperwork or labels from a report request

or certificate report requests can be generated from a report request

Generate certificate reports from report requests

Generate certificate reports from a report request

Note: Although jobs with different ARCHIVE_STATUS values can be added to a report request, a report can ONLY be generated if all of the jobs on the report request have the same ARCHIVE_STATUS. There is a validation and error message that prevents this. This was introduced so that the report generation will NEVER have to go across multiple partitions.

Active Status of a Report Request Report

A report request report must be active for its output to be created.

Report Generation on the System Batch Queue

To generate reports from a report request, the report generation batch job is placed on the system batch queue.

  • A CCBRGEN system batch job is created in the system batch queue for the report request. Refer how to Set the BATCH_QUEUE_TASK_PRIORITY Preference.

  • Execution of a CCBRGEN system batch job is subject to queue limits to ensure that excessive tasks for the same job type are not created within a fixed time period, but are ignored, thereby protecting the system batch processor from overload. Refer to Configuring the System Batch Queue for protecting the system batch queue from excessive requests.

  • The batch job history and the execution steps are visible for an historical job in the History tab for the report request. Refer to Maintaining Schedules and Batch Job Executions.

The report documents are generated from the associated report request:

  • The template is read to determine the required core result sets.
  • If the template is a ZIP file that contains a DSC (direct source connection) file, then the DSC locates the additional data source/s and creates extra result sets from there.
  • Both the core and DSC-based result sets are populated.
  • Both the core and DSC-based result sets are packaged up and sent to the report engine along with the template, and the format required for the output.
  • The report engine extracts text from multi-lingual fields in the required language(see Report Language below).
  • The report engine rounds numeric final values to produce formatted final values in the result sets. The USE_CORRECTED_LOWER_DET_LIMIT and USE_CORRECTED_UPPER_DET_LIMIT application preferences are used by the rounding algorithm. Refer to the Rounding and Formatting Results and Calculating Uncertainty appendix.
  • The report engine returns the output file.
  • Report distribution takes place, if specified.

  • During this report generation process:

  • If the REPORT_SCRIPT application preference exists and is linked to a report script code then at each hook point in the report generation process, the related event in the script is run.
  • If the template is linked to a report script code then at each hook point in the report generation process, the related event in the script is run.
  • The system batch queue is used to perform the processing, including the distribution. The result of the batch job execution can be seen on the History tab of the CCRPTR—Report Request application.

  • On each report request report, the Last File Name is updated.

The report generation event is audited, with the audit record's Field set to 'Report Filename' and the From Description set to the output filename.. Refer to Reviewing Operational Data Audits.

Consideration of Job Status and its Impact on Report Status Type

If a report request's Report Request Type is Certificate, and the report request contains any cancelled jobs, then reports cannot be generated from the report request. Otherwise, the Generate Report dialog box is presented to allow for the selection of the Report Status Type:

  • Internal
  • Preliminary—Where the selected Report Status Type is Preliminary or Final, but ANY job in the report request is not started (the job's Started Date is empty), then the Report Status Type falls back to Internal.
  • Final—Where the selected Report Status Type is Final, and all jobs are started but ANY job in the report request is not completed (the job's Completed Date is empty), then the Report Status Type falls back to Preliminary.

The Report Status Type is exposed for use in custom report scripts. The Report Status Type is set on the generated certificate report, and used when Maintaining Generated Reports as a search criteria to search for certificate reports in the CCREPT—Search Report screen.

Report Code and Number

Each generated report is given a code and number that are generated from syntaxes: Configure a Syntax to Generate Report Codes, and Configure a Syntax to Generate Report Numbers.

Population of the Reportable Result Set

The report engine extracts text from multi-lingual fields in the language defined by the report request report's Language.

If the template is a ZIP file that contains a DSC (direct source connection) file, then the DSC locates the additional data source/s and creates extra result sets from there.

Both the core and DSC-based result sets are populated.

Both the core and DSC-based result sets are packaged up and sent to the report engine along with the template, and the format required for the output.

The report engine extracts text from multi-lingual fields in the language defined by the DEFAULT_REPORT_LANGUAGE preference.

Refer to Technical Documentation—Job Reports for information on populating reportable result sets and views.

Report Language

The report engine extracts language-specific text from the multi-lingual fields based upon the report request report's language. Refer to Reporting in Alternate Languages.

The population of the reportable result sets is done for each report request report, even if multiple report request reports contain the same language. This is because the content of the reportable result set for each report request report is driven by the content of the report request report's report template. Therefore the population has to occur for each report request report, to ensure that the content is available for the filling of the report using the report template.

Rounding and Formatting of Reportable Results

The report engine rounds numeric final values to produce formatted final values in the result sets. The USE_CORRECTED_LOWER_DET_LIMIT and USE_CORRECTED_UPPER_DET_LIMIT application preferences are used by the rounding algorithm. Refer to the Rounding and Formatting Results and Calculating Uncertainty appendix. Refer to the Effect of Scheme Scope upon Calculating Uncertainty in Certificate Reports.

Rounding and Formatting Results and Calculating Uncertainty

When certificate reports are generated, the following attributes are used in the rounding and formatting process from the CCReportRequestSampleSchemeAnalyte:

  • reportUnitCode/reportUnitId, inherited from the sample scheme analyte
  • reportLowerDL, inherited from the sample scheme analyte
  • reportUpperDL, inherited from the sample scheme analyte
  • roundingTableCode/roundingTableId, inherited from the sample scheme analyte

and from the linked scheme version analyte:

  • allowReportNonValData
  • roundingMethodType
  • reportDisplayMask
  • roundingScriptCode/roundingScriptId

and from the CCSampleSchemeAnalyte:

  • NumericFinalValue, BooleanValue, DateTimeValue or TextValue, depending on the DataType

The current report request interface does display report request sample schemes or analytes. However, after sample scheme schemes and analytes are added to a report request, when a report request scheme or analyte is updated, the reportability is pushed down to each related report request sample scheme or analyte, respectively. Therefore to update the report request sample scheme analyte attributes that are used in the rounding and formatting process, update the following CCReportRequestSchemeAnalyte attributes to have them pushed down to the CCReportRequestSampleSchemeAnalyte level:

  • analyteReportUnitCode/analyteReportUnitId
  • analyteReportLowerDetectionLimit
  • analyteReportUpperDetectionLimit
  • analyteRoundingMethod
  • analyteRoundingTableCode/analyteRoundingTableId

The rounding and formatting process set the following attributes:

  • In the CCReportRequestSampleSchemeAnalyte
    • formattedFinalValue
    • formattedReportLowerDL
    • formattedReportUpperDL
    • uncertaintyValue
  • In the CCSampleSchemeAnalyte, where the report is a Final report:
    • formattedFinalValue
    • formattedReportLowerDL
    • formattedReportUpperDL
    • uncertaintyValue

Presentation of Results

For a preliminary or final report, the following table indicates how results are rounded and presented on the report.

If the sample scheme analyte's Workflow Status is Completed, then rounded result is displayed on the report.

If the sample scheme analyte's Workflow Status is Listed Not Received, Insufficient Sample, Not Analysed or No Result, then the report string associated with the core workflow or user workflow is displayed on the report instead of the rounded result.

If the sample scheme analyte's Workflow Status is something other than Completed, Listed Not Received, Insufficient Sample, Not Analysed or No Result, then a substitute string is displayed on the report. The substituted strings are entered as System Table Codes with a Table Type of CC31—Workflow Statuses, as configured in the MSETBL—Table Code Service application, and if not defined there, then 'NVL' (Not Validated) is used as the string. This prevents accidental or premature reporting of unvalidated results to the client.

              Once the report is generated:
Report Request Type Requested report Status Type

SSA Result

(Numeric Final Value)

 SSA Workflow Status SSA User Workflow Status Preference TRANSFER_RRSSA_REPORT_DATA_TO_SSA Table Description in User Workflow Status table CC30 RRSSA Formatted Final Value SSA Formatted Final Value

Certificate

 

Preliminary or Final

 

Exists

 

Completed

 

Not relevant

 

True

Not relevant

Rounded SSA result

Copied from RRSSA

False

Not relevant

Rounded SSA result

Set to NULL

Certificate

 

Preliminary or Final

 

Exists

 

LNR, IS, NA, NR

 

Does not exist

 

True

Not relevant

*Hard-coded report string related to Workflow Status

Copied from RRSSA

False

Not relevant

*Hard-coded report string related to Workflow Status

Set to NULL

Certificate

 

Preliminary or Final

 

Exists

 

LNR, IS, NA, NR

 

Exists

 

True

Exists

**Referenced Table Description related to User Workflow Status from CC31

Copied from RRSSA

False

Exists

**Referenced Table Description related to User Workflow Status from CC31

Set to NULL

Certificate

 

Preliminary or Final

 

Exists

 

LNR, IS, NA, NR

 

Exists

 

True

Does not exist

User Workflow status Table Code

Copied from RRSSA

False

Does not exist

User Workflow status Table Code

Set to NULL

Certificate

 

Preliminary or Final

 

Exists

 

NOT (Completed, LNR, IS, NA, NR)

 

Not relevant

 

True

Not relevant

Hard-coded report string 'NVL'

Copied from RRSSA

False

Not relevant

Hard-coded report string 'NVL'

Set to NULL

*Hard-coded Report String related to Workflow Status:

SSA Workflow Status Enum

Hard-coded Report String

4

LNR

20

IS

19

NA

10

NR

Example: **Referenced Table Description related to UserWorkflow Status from CC30

Note: CC30 is an optional user setup table and is not part of core data. If upon lookup, the user workflow status cannot be matched with the Table Code, then the report displays what the user has entered.

Table Type Table Code Table Description Associated Record Active flag

XX

CC30

User Statuses

 

Y

CC30

BRK

Sample Breakage

20

Y

CC30

CONT

Sample Contaminated

19

Y

CC30

IS

Insufficient Weight

20

Y

CC30

LIL

Lost In Lab

20

Y

CC30

LIP

Lost In Prep

19

Y

CC30

LNR

Listed Not Received

4

Y

CC30

NA

Not Analysed

19

Y

CC30

NR

No Result

10

Y

CC30

OVR

Over Range

19

Y

CC30

RTC

Result To Come

10

Y

CC30

UNSEALED

Sample Unsealed

19

Y

Transfer of Final Results

The TRANSFER_RRSSA_REPORT_DATA_TO_SSA application preference is set to transfer final results from a final report back to the sample scheme analytes.

Depositing of a Report into the Report Repository

The details of each report are created in the report repository:

Report Distribution

After the report generation process is completed, the documents are distributed automatically as per the distribution details set up on each report request report.

Note: If an error is raised on emailing or printing a generated report, then any subsequent reports are NOT generated in the session. If this occurs, then each report needs to be generated individually by changing the Reportable flag so that only one report is generated at a time. This allows for the generation of the report even where there are emailing or printing issues.

If distribution is in place for the reports, the system batch job does distribution.

If there are multiple reports on a report request, and email and print is requested for all of them, during report generation, only one CCBRGEN system batch job is created in the system batch queue, and emailing and printing occurs as part of that task. If there are errors in connecting to the email server or the printer, then the reports are still created but they are not emailed or printed. The event is audited.

Emailing

  • If the report request has a Report Type of Certificate and a Workflow Status of Internal, then the generated certificate reports are not emailed at all, regardless of the settings on the Email tab.
  • If the report request has a Report Type of Certificate and a Workflow Status of Preliminary or Final, and the report request report's Email is selected, then the generated certificate reports are emailed as per the distribution details on the Email tab.
  • If the REPORT_FROM_EMAIL_ADDRESS application preference is defined and contains a valid email address, when the generated reports are emailed, then the Email From email address is set to this email address.
  • If the EMAIL_BCC application preference is defined and contains a valid email address, when the generated reports are emailed, then the BCC email address is set to this email address.
  • If a syntax exists that is in scope and has a Syntax Type of Report Request and a Syntax Code of EMAIL_SUBJECT_TEXT preference, when entering distribution details for a report, then the email subject body contains the text generated by the syntax. Note that this syntax should evaluate only to a single-line subject.
  • If a syntax exists that is in scope and has a Syntax Type of Report Request and a Syntax Code of EMAIL_MESSAGE_TEXT preference, when entering distribution details for a report, then the email message body contains the text generated by the syntax.
  • If the EMAIL_REPORTS_SEPARATELY application preference is defined and selected, when generated reports are emailed, then each individual report is sent in a separate email to the contact. If the EMAIL_REPORTS_SEPARATELY application preference is not defined, or is defined and is cleared, when generated reports are emailed, then each individual report is sent in the same email to the contact.
  • If the EMAIL_ZIP_ATTACHMENTS application preference is defined and selected, when the generated reports are emailed, then one zip file containing all of the generated reports is emailed as an attachment to the email. If the EMAIL_ZIP_ATTACHMENTS application preference is not defined, or is defined and cleared, when the generated reports are emailed, then multiple attachments are added to the email/s.
  • If the client contact's email has multiple email addresses or the report request's To field is modified to have multiple email addressed, then an email is sent to all listed recipients.

Printing

  • If the report request report's number of Print Copies is greater than zero, then that number of copies of the report is printed on the Printer device if it is defined.
  • If there are multiple reports on a report request, and email and print is requested for all of them, during report generation, only one CCBRGEN batch job execution is created, and emailing and printing occurs as part of that task. If there are errors in connecting to the email server or the printer, then the reports are still created but they are not emailed or printed. The event is audited. Refer to Maintaining Schedules and Batch Job Executions.
  • If the report request report's number of Print Copies is greater than zero, then that number of copies of the report is printed on the Printer device if it is defined.

Copying to folder

  • If Copy to Folder is checked on the Reports tab, the generated reports are copied to the folders defined by the additional reporting method's Detail, for each client contact's additional reporting methods where the additional reporting method's Report Method Type is Folder.

Report distributions by email, printing or saving to a folder, or when any of these attempts fail, are audited.

Updates in the Job upon Certificate Report Generation

For any job, job scheme or job scheme analyte associated with the report, various dates are updated based upon the Report Status Type:

  • Internal report—No updates to any dates
  • Preliminary report—First Reported Date is updated if it is Null
  • Final report—First Reported Date is updated if it is Null, Last Reported Date is updated if it is Null.

Auditing of the Reporting Process

The report generation event is audited in which the audit record's Field is set to 'Report Filename', and the From Description is set to the output filename.

An audit event is recorded each time a report is generated. Where multiple reports are generated from a report request in a single session, then each created filename is audited separately upon creation.

Changes to dates in the job are audited.

Report Distribution at a Later Time

A certificate report document generated using this activity is displayed on Generated Reports tab, and can be distributed again from here or downloaded and re-printed. Refer to the Distributing Certificate Reports.

Maintaining Historical Certificate Reports

Historical reports generated from certificate report requests are placed in the report repository from where they can be searched and reviewed. Refer to Maintaining Reports in the Report Repository.