Report and Datasource Engine Modules

The DocX and RML report engines use datasource (DS) to generate reports. Both report engines allows you generate reports using their respective format.

All these 3 engines can be invoked using either the user interface in the Repository module or through the ETL chainset in the ETL module.

The Repository module has a job queue to allow multiple jobs to be triggered on the same report. Some delay may be experienced on the return results or reports if there are jobs that need to be completed before yours could begin.

Module Interface

To use the user interface to access the DocX, RML and DS engine modules, you need to have the privilege to access the Repository module. To use ETL chainset to access these engines, you need to have the privilege to access the ETL module.

Interface	Description	Required Privilege
DocX Engine	Allows DocX Report Engine access.	mod-docx-engine
RML Engine	Allows RML Engine access.	mod-rml-engine
DS Engine	Allows DS Engine access.	mod-ds-engine

Datasource Engine

A data source file is a collection of records that store data. The DS file is used by the DocX and RML report engines to generate reports.

The DS engine can be invoked either through the user interface in the Repository module or the ETL chainset in the ETL module.

Generate DS Via Repository

The user interface in the Repository module allows you to use the DS engine to convert the data into different types of file format. Currently JSON, XLSX and CSV format are supported.

To generate an output file, select the desired DS file and click on the “Generate” button in the Repository module.

The Datasource Engine page will appear.

Select the desired output file format in the “Generate as” field. In the “To” field, select whether to open the output file using the browser or save to disk. Click on the “Generate” button to generate the output file.

If JSON is the selected output file format, the schema of the DS file is generated and save in the JSON file as well.

Generate DS Via ETL

Another alternative way to generate DS to is to use the ETL chainset.

Using the ETL above, the ETL chainset generates and loads the DS.

DocX Report Engine

The DocX Report Engine make use of a DocX file and the DS file as data to generate the required report.

The DocX report engine can be invoked either through the user interface in the Repository module or the ETL chainset in the ETL module.

DocX File

The DocX file is a template that contains the format and defines which DS file to use to generate the report.

Below is an example of a DocX file. The upper part of the DocX file defines the format of the report. The first line below the table defines the location of the DS file. The rest defines the order and the format of the fields used.

The DS file must reside in the location defined in the DocX file, otherwise an empty report will be generated.

Generate DocX Via Repository

To generate the report using the user interface of the Repository module, select the DocX document and click the “Render” button.

The DocX Report Engine page will appear.

Key in the desired city in the “city” field. In the “Render as” field, select the desired output format. Currently only DocX format is supported. Click on the “Render” button.

In the example below, the city defined is “Haney”. The report is generated using the DS file as content and the DocX file as template.

Generate DocX Via ETL

Another alternative way to generate DocX report is to use the ETL chainset.

In the simple example below, the ETL chainset generates the DocX report and writes to a DocX file.

This ETL chainset performs the following:

• Reads in a JSON record indicating the DocX file and the required parameters
• Generates DocX report using the parameters in the JSON record, as well as the parameters defined in the DocX file
• Writes the output file to the desired location and filename

Click on the “Run Steps” icon to generate the DocX report.

RML Report Engine

Similar to the DocX Report Engine, the RML (Redline Markup Language) Report Engine uses the DS file as data source and a RML file as template. The file with RML extension file contains annotations, markers and other information (such as location of the DS file) stored in XML format.

The RML report engine can be invoked either through the user interface in the Repository module or the ETL chainset in the ETL module.

Generate RML Via Repository

To generate the RML report through the Repository module, select the RML document and click the “Render” button.

The RML Report Engine page will appear.

Select the desired format (PDF or XLSX) from the drop-down list and click on the “Render” button. The report is generated using the DS file as content and the RML file as template. If the browser permit, the report is displayed in another tab.

There is an option to display the generated report in the RML Report Engine page. To do so, you will need to add the following line into the application.conf file to allow the page to display the report in PDF format:

ambience.rml-engine.ui-left-parameters = [ "application/pdf"]

If the browser permits, you can also display HTML or XLSX format in the RML Report Engine page. You simply change the pdf to the desired format in the additional line to be added into the application.pdf file.

You will need to restart the server for the display to take effect. The generated report will be displayed in the RML Report Engine page instead of another browser tab.

You can opt to close the left panel to maximise the report in the page by clicking on the “Hide Parameters” icon on the left of the left panel.

To expand the left panel, click on the “Show Parameters” icon on the upper left corner of the page.

Generate RML Via ETL

Another alternative way to generate RML report is to use the ETL chainset. There are several ETL that can be used to generate the RML report.

In the simple example below, the ETL chainset generates the RML report and writes to a PDF.

This ETL chainset performs the following:

• Generates RML report in the desired output format
• Writes the output file to the desired location and filename

Click on the “Run Steps” icon to generate the RML report.