Maathra

Comprehensive Guide to Installing and Configuring Maathra ReportFactory

Comprehensive Guide to Installing and Configuring Maathra ReportFactory

Setting Up Maathra ReportFactory for Optimal Performance

Arun Mohan's photo
Arun Mohan
·

9 min read

Table of contents

Introduction

This guide explains how to install and configure Maathra ReportFactory. Although it is primarily intended for Oracle non-autonomous databases, the majority of the configuration steps apply to both autonomous and non-autonomous databases. For configurations specific to the autonomous database, please follow the additional steps mentioned here.

Integrating Oracle Autonomous Database with Maathra ReportFactory - Backend

ReportFactory Installation Requirements

Database Requirements

  • Oracle Database 19c or above: Maathra ReportFactory is compatible with earlier versions of the database. However, the administrative UI of ReportFactory is built using Oracle APEX 23.2, which necessitates Oracle DB 19c. We plan to release another version of the administrative app that supports an older version of Oracle APEX soon. However, you can use a lower version of Oracle Database as a data source.

Oracle JDBC

  • Maathra ReportFactory requires Oracle JDBC v8 or higher. The certified version is 8-23.2.00.

Oracle APEX Requirements

  • Maathra ReportFactory requires Oracle APEX 23.2.0 or higher.

Browser Requirements

  • Maathra ReportFactory requires a JavaScript-enabled browser and supports the current and prior major releases of Google Chrome, Mozilla Firefox, Apple Safari, and Microsoft Edge.

Web Server Requirements

  • ReportFactory requires Apache Tomcat 9.

Disk Space Requirement

  • A minimum of 100 MB of disk space is required for the installation and configuration of ReportFactory.

ReportFactory Installation Overview

This document describes how to install Maathra ReportFactory in an on-premises database (or local installation). For autonomous database configurations, please follow the additional steps mentioned here.

Components of ReportFactory

  • apex-report-factory.war file: The report engine that exposes REST APIs to generate reports. This WAR file is deployed in Apache Tomcat.

  • APEX web app: Configures and manages Maathra ReportFactory.

  • Report templates (.jasper files): Generated using Jaspersoft Studio. Maathra ReportFactory utilizes Jasper Report libraries to generate reports. Use any version of Jaspersoft Studio that supports Jasper Report library version 6.17.

Installing and Configuring ReportFactory

Download

Maathra ReportFactory is free to download and use in both development and production environments, with no licensing requirements. Please note that there are some limitations on the number of reports that can be generated per hour if you are using Always FREE Edition. ReportFactory can be downloaded from https://www.maathra.com/apex-report-factory.

Installing Maathra ReportFactory APEX Application

  • Create a new workspace and database schema to install the APEX application and store the metadata, respectively.

  • Log in to the newly created workspace.

  • Go to App Builder and import the Maathra ReportFactory SQL file.

  • Follow the on-screen instructions to complete the installation process.

  • Upgrade the supporting objects by navigating to Application → Supporting Objects → Click "Upgrade Supporting Objects" from the right-side menu.

  • Review the installation summary. In case of invalid objects after the installation, recompile them using the script available in the utilities folder.

Configuring Application Access Control

  • Go to Shared Components → Security → Application Access Control.

  • Click "Add User Role Assignment".

  • Enter the username, check "Administrator", and click Save.

Installing Maathra ReportFactory Engine

Configuring Report Template Directory

  • Create the folder structure as given below on the server. Alternatively, copy and paste the folders from the ReportFactory download(recommended):

    • report-engine: Main directory

      • logo: Folder to upload logos or static files.

      • reports: Folder for generated reports and logs.

      • templates: Folder to upload report templates.

      • wallets: Folder to upload Oracle Cloud Wallets to establish the connection to Oracle Autonomous Databases.

      • license.txt: Optional license file.

  • Copy the absolute file path. In this case C:\report-engine

Configuring Report Directory in Apache Tomcat

  • Goto Apache Tomcat “conf” folder. Tomcat root directory → conf

  • Create a file apex-report-factory.properties inside the conf folder or copy the sample file provided in the download.

  • Update the following properties in the property file and save.

    • saveReport=Y

    • saveReportOn=FILE

    • rootPath=C:\report-engine\ <-- Replace the file path in your server

  • Understanding properties

    • saveReport: Possible values are Y and N. If set to N, the generate output file will not be saved in DB or in the file system

    • saveReportOn: Possible values are FILE and DB. If set to DB, the generated output will be stored in the database. If set to FILE, the output will be saved in rootPath\reports

    • rootPath= Location of the report engine

        # To mark generated report should be saved or not 
  saveReport=Y
  # The generated report should be saved in, possible values ar: DB / FILE
  saveReportOn=FILE
  # Specifies the path of report storage if saveReportOn=FILE
  rootPath=C:\\report-engine\\

  # Specifies the database dialect for Oracle.
  hibernate.dialect=org.hibernate.dialect.OracleDialect

  # Specifies that Hibernate should not make any changes to the database schema.
  hibernate.hbm2ddl.auto=none

  # Uses the default naming strategy provided by Hibernate.
  hibernate.ejb.naming_strategy=org.hibernate.cfg.DefaultNamingStrategy

  # Disable SQL output in production environment.
  hibernate.show_sql=false

  # Disable SQL formatting in production environment.
  hibernate.format_sql=false

  # Define any necessary synonyms for production environment.
  hibernate.synonyms=none

  # Enable auto-commit mode for production environment.
  hibernate.autoCommit=true

Configuring Application Datasource in Apache Tomcat

  • Edit the context.xml file in the conf folder and add the data source details.

  • For non-autonomous database

      <Resource maxWaitMillis="10000" maxTotal="400" maxIdle="30" driverClassName="oracle.jdbc.driver.OracleDriver" password="password" username="username" name="jdbc/primary" auth="Container" url="jdbc:oracle:thin:@host:port/servicename" type="javax.sql.DataSource"/>

  • For autonomous databases refer this article. Configuring Oracle Autonomous Database as a Datasource for ReportFactory

  • Sample context.xml

      <?xml version="1.0" encoding="UTF-8"?>
  <!--
    Licensed to the Apache Software Foundation (ASF) under one or more
    contributor license agreements.  See the NOTICE file distributed with
    this work for additional information regarding copyright ownership.
    The ASF licenses this file to You under the Apache License, Version 2.0
    (the "License"); you may not use this file except in compliance with
    the License.  You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
  -->
  <!-- The contents of this file will be loaded for each web application -->
  <Context>
      <!-- Default set of monitored resources. If one of these changes, the    -->
      <!-- web application will be reloaded.                                   -->
      <WatchedResource>WEB-INF/web.xml</WatchedResource>
      <WatchedResource>WEB-INF/tomcat-web.xml</WatchedResource>
      <WatchedResource>${catalina.base}/conf/web.xml</WatchedResource>
      <Resource maxWaitMillis="10000" maxTotal="400" maxIdle="30" driverClassName="oracle.jdbc.driver.OracleDriver" password="password" username="username" name="jdbc/primary" auth="Container" url="jdbc:oracle:thin:@host:port/servicename" type="javax.sql.DataSource"/>
     <!-- Uncomment this to disable session persistence across Tomcat restarts -->
      <!--
      <Manager pathname="" />
      -->
  </Context>

Sample configuration files are available in the Maathra ReportFactory download.

Download and deploy Oracle JDBC

Deploy Maathra ReportFactory in Apache Tomcat

  • Copy apex-report-factory.war to the Tomcat webapps folder.

  • Tomcat Root Folder → webapps

  • Restart the Tomcat

Verifying the Installation

  • Open a web browser and enter the ReportFactory status URL.

      http://host:port/apex-report-factory/scheduler/checkstatus

  • If the server responds with code 200, the installation is successful.

  •         {"code":"200","message":"All Maathra ReportFactory services are up and running."}

Troubleshooting Common Issues

  • Mostly the installation is unsuccessful due to file permission issues. The OS user running the Tomcat must have read-write access to all folders in the Report Template Directory and read access on the property file created.

Configuring Maathra ReportFactory using the APEX application

  • Log in to the Maathra ReportFactory APEX application.

Update Org Details

  • Update the Organization code and name by visiting Menu → App Settings → Org Preference

    • Enter the Org Code and Org Name and click save

    • Reports will not be generated if Org details are not updated.

    • Org ID is a unique ID for the Maathra ReportFactory installation.

Generate Client ID and Secret

Maathra ReportFactory is a REST web service. Reports are generated by calling the REST endpoints, which are protected using token-based authentication. The client must include a valid token in every request, containing the Client identifier. To generate a valid token, a Client ID and Client Secret must be generated.

  • Menu → App Settings → Client Credentials → Add New Client Credential

  • Enter a Client name and click Create.

  • Multiple Client Credentials can be generated.

Configure Report Data Source (Non-autonomous Oracle Database)

Data Source is the source of data for generating reports. It is a database schema. Maathra ReportFactory support connecting to multiple data sources of type Oracle.

For connecting Oracle Autonomous Database refer to this article. Configuring Oracle Autonomous Database as a Datasource for ReportFactory

  • Menu → App Settings → Datasources

  • Click Add New Datasource

  • Fill in the details and click Create.

    • Short Code: A unique code to identify data source. Use alphanumeric characters and _.

    • Source Name: Descriptive name for the data source

    • Source Type: Oracle

    • Host: Fully qualified domain or IP address of the database server

    • Port: Port number of the database

    • SID: Database identifier

    • Service Name: Service name

    • Username: Database user

    • Password: Password of the database user.

    • This setting is similar to the connection settings in SQL Developer.

  • Click on the Datasource shortcode to edit the data source details if required.

Domain Whitelisting

Maathra ReportFactory can be configured to accept incoming requests from limited domains. To allow connections from all domains use '*'.

  • Menu → App Settings → Whitelisted Domains → Add New Domain

  • Enter * under Domain and click Apply Changes.

Run Sample Report

Maathra ReportFactory comes with a sample PDF report to verify the connection.

  • Menu → Report Definition

  • Open ‘HELLO_WORLD’ and click the Edit icon.

  • Update the Datasource the Datasource just created and click Apply Changes.

  • Click ‘Generate Code’ and then click test run.

  • If the data source configuration is correct, a new tab will be opened and a sample report as shown below will be generated.

  • Your browser may block the opening of new tabs. Please check this if the report is not generated.

  • A blank report will be generated if there is any error. Check the server log as well as the log in ReportFactory by navigating to Menu → Job History

  • The history page lists all previous runs of any reports. Reports can be downloaded from the history page, and the log is also available for download.

Advanced Settings

Configuring Oracle Directory

MaathraReport factory can be configured to upload report templates using the web app to the report server if the database and the report server are on the same host.

  • Connect to Oracle Database as a sys user and grant CREATE DIRECTORY privilege to the ReportFactory user

      GRANT CREATE ANY DIRECTORY TO <ReportFactory Schema User>;

  • Connect to the ReportFactory user and create the directory.

          CREATE OR REPLACE DIRECTORY MTC_ARF_DIR AS 'C:\report-engine\templates';

    We hope this guide provides you with all the necessary information to successfully install and configure Maathra ReportFactory. By following the steps outlined, you should be able to enhance your reporting capabilities and make the most of your data. For further assistance or additional information, please contact our customer service team at . Thank you for choosing Maathra ReportFactory, and we look forward to supporting your business needs.

ReportFactoryorclapexpdfmaathra