Reporting

How to prepare reports for users

• Sections about the reporting support
• Reporting support – general description
• Translations
• Enable report for user
  • Download the report by user
• Calling second report
  • Right control
  • Store report to the object
• Report options
  • Available and supported report options
• Attach files to the PDF report

Sections about the reporting support

• Support for various data types
• General reporting based on the object definition
• Support for hierarchical object structure
• Support for list objects

Reporting support – general description

Support for reports are designed for system developers and administrators, not for final users. Installation that requires user-defined reports should use external modules and link them with the database.

AyMINE internally uses TCPDF library for report generation but the library is never directly used.

Translations

For each langugage supported by the AyMINE installation should be a defined a file /sys/langs/<lang>/TCPDDFLang.php with definition of the translation strings. (However it currently translates only page)

Enable report for user

Objects that supports reporting – generation of the list of objects or object detail to the PDF does not have to define method for report generation. The general report is supported by the framework internally.

View (both list or detail) that contains reportable objects set mark with information that reporting is supported:

<view_name>:{
   "parameters":{ 
      "printOperation":true | <system counter name> | { <system counter definition> }
   }
}

Dashboard view has its own menu definition and so dashboard does not create the button for report. Nevertheless, dashboard supports the report call as well, but the location where is the call in the menu should be defined by the dashboard menu in the jsonc file. Simply add the menuItem fields like in the example:

"this":{ "menuItems":{ "printOperation": { "a":"window.printOperation"} } }

Neither item name translation nor the icon definition is necessary because both has standard definition in the application.

Application creates function for report in the view menu Store to PDF. Application always calls method server.<objectName>.PDFToDownload for detail or PDFListToDownload for list view. However, objects have no reason to implement these methods because they are implemented generally by the persistentObject abstract ancestor.

Objects should implement the getReport method:

public static function getReport(reportDesc $rep): htmlPattern

(See the persistentObject for more details about the method).

Download the report by user

Generated reports are always stored in the temporary file and user never gets the name of the file. Report is downloaded by calling the method window.getLastGenfile. That request server to provide the file and starts download.

Warning: getLastGenfile method calls php method /getLastGenfile.php to download the file. Some firewalls could block the call. AyMINE file access requires right to download a file calling the /getLastGenfile.php script.

Calling second report

Objects that should support more than a single report could use the decision during the default report operation or create its own method to generate the report.

Example:

"getDetailReport":{ 
   "readonlyenabled":true,    // enable method for read-only objects
   "icon":"list__pdf",        // icon of the method
   "enabled":"=!obj.isNew",   // condition, when function is available – new object cannot be reported
   "command":[
      // Request report – general method is used but different template 
      "server.this.PDFToDownload(templateVersion=complete)",
      // Request to download the generated file
      "window.getLastGenfile"
   ]
}

Right control

User can request report only in case that:

• Has right to export data from AyMINE – system right frm@frmObject:export. Right is part of the default sytem user group sys/Active user sys.
• Has right to read object(s)

When user selects list of objects, right to read the object is checked for each selected object. When user generates object that has subordinated objects, right to read the object is controlled only for top-level object, not for subordinated. (Right to read object is always expected to be also valid for subordinated objects.)

Store report to the object

Report can also be directly stored to an object. However, the request should be processed by server business method. Client application without server support cannot initiate it. Server function should check that it is not called repeatedly and that the client does not generate too many stored reports that could overload the system. (Always remember that client application could be a cheat.

Report options

Each view / object can define its own report attributes. When defined, user gets list of options to select the report parts (or other options). Options should by defined by the system counter. Name of the counter is defined by the printOperation view parameter:

• viewParameter:true – generate report without any option
• viewParameter:/<enumName> – open the selection of options defined by the system counter
• viewParameter:{"enum":/<enumName>, "enumLimit":"condition"} – open the selection from the system counter and apply the enumLimit condition on the counter fields to select right options.

User selection from of the report parts is locally stored and user has report options fields set from the last report usage.

Available and supported report options

Each report could define its own supported list of options. However, some options are supported by the framework. They are defined in the frmFrm object:

• repOption_files – Attach files from the reported objects (see hereinafter for description)
• repOption_subitems – Generate also subordinated objects. Option is defined but the report script should check it; there is no system support to manage the option.

Attach files to the PDF report

Files stored at objects can be attached to the report as the PDF attachments. The attached files are listed at the end of the PDF.

The file attachments are stored to the PDF by one of the PDF creator method:

• addFileObject – Attaches files from single object
• addFileList – Attaches files from all objects that are in the report

Both functions are called automatically by the report generator, if report has active report option. Script should call them only when report is not generated by the default methods from the persistentObject.

The default function does not store files:

• With mark hidden
• With status out or rejected

The method that stores file as attachments does not generate any details about them. Script should call the sysFile::htmlListReportPart method for each object to generate the table with information about the attachments.

The htmlListReportPart generates information about all files except hidden (particularly it creates information also about rejected and removed files.