# Comprehensive Guide to Installing and Configuring Maathra ReportFactory

## 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](https://blog.maathra.com/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.](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.
    
    ![](https://cdn.hashnode.com/res/hashnode/image/upload/v1716307321394/b65db9e5-d44b-4329-9c0e-23145679016e.png align="center")
    
* Go to App Builder and import the Maathra ReportFactory SQL file.
    
    ![](https://cdn.hashnode.com/res/hashnode/image/upload/v1716307467783/0d7d2e59-1404-4e32-9dd5-0fa175337520.png align="center")
    
    ![](https://cdn.hashnode.com/res/hashnode/image/upload/v1716307524780/6536d65e-5838-435a-afbb-ace2cdc2b1c2.png align="center")
    
* 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.
    
    ![](https://cdn.hashnode.com/res/hashnode/image/upload/v1716309840026/cc23fd55-8fd6-4661-b4ce-ec2f8da5ed3d.png align="center")
    
* 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.
    
    ![](https://cdn.hashnode.com/res/hashnode/image/upload/v1716309271377/31582c60-4091-4a4c-8820-61cbc0de0f24.png align="center")
    
* Click "Add User Role Assignment".
    
    ![](https://cdn.hashnode.com/res/hashnode/image/upload/v1716309288403/a87acee4-0bec-49ab-807f-70f0668ed6b5.png align="center")
    
* 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.
            
    
    ![](https://cdn.hashnode.com/res/hashnode/image/upload/v1716309429512/1d9f5e80-1b75-44a5-85f5-cf97d6b45c04.png align="center")
    
* 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
        
        ```plaintext
        # 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
    
    ```xml
    <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](https://blog.maathra.com/configuring-oracle-autonomous-database-as-a-datasource-for-reportfactory)
    
* Sample context.xml
    
    ```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

* Download the Oracle JDBC.jar version 8-23.2.00 and upload it to the Tomcat lib folder.
    
* [https://mvnrepository.com/artifact/com.oracle.database.jdbc/ojdbc8/23.2.0.0](https://mvnrepository.com/artifact/com.oracle.database.jdbc/ojdbc8/23.2.0.0)
    
* Tomcat Root Folder → lib
    
    ![](https://cdn.hashnode.com/res/hashnode/image/upload/v1716346735329/cdc3570b-a349-4875-bccf-30c137f08327.png align="center")
    

#### 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.
    
    ```xml
    http://host:port/apex-report-factory/scheduler/checkstatus
    ```
    
* If the server responds with code 200, the installation is successful.
    
* ```json
          {"code":"200","message":"All Maathra ReportFactory services are up and running."}
    ```
    
    ![](https://cdn.hashnode.com/res/hashnode/image/upload/v1716346838848/cdccf202-c1df-48b3-9af9-7245d3356cde.png align="center")
    

#### 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.
    
    ![](https://cdn.hashnode.com/res/hashnode/image/upload/v1716346882711/6772d130-878d-4660-8366-3a470e020403.png align="center")
    

#### 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.
        
        ![](https://cdn.hashnode.com/res/hashnode/image/upload/v1716346990899/05981a28-0437-4997-a7e0-94dc99294f59.png align="center")
        

#### 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.
    
    ![](https://cdn.hashnode.com/res/hashnode/image/upload/v1716347137579/14ba74de-c3af-470d-ad7b-e67fd4da0ad0.png align="center")
    

#### 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](https://blog.maathra.com/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.
        
    
    ![](https://cdn.hashnode.com/res/hashnode/image/upload/v1716347258690/4158ec1a-b680-43c5-87f8-bb4610dc6f6a.png align="center")
    
* 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.
    
    ![](https://cdn.hashnode.com/res/hashnode/image/upload/v1716347499547/aead2da3-a55c-4a42-a0b8-cc0fdbac9819.png align="center")
    

#### Run Sample Report

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

* Menu → Report Definition
    
    ![](https://cdn.hashnode.com/res/hashnode/image/upload/v1716347577501/5b7642b1-c184-4934-ac35-4e5b32f487f1.png align="center")
    
* Open ‘HELLO\_WORLD’ and click the Edit icon.
    
    ![](https://cdn.hashnode.com/res/hashnode/image/upload/v1716347594858/db6532ad-0cb8-4c1c-8f90-b1e6f9076d49.png align="center")
    
* Update the Datasource the Datasource just created and click Apply Changes.
    
    ![](https://cdn.hashnode.com/res/hashnode/image/upload/v1716347618869/60d1334d-98de-4703-be93-1444a968a8f9.png align="center")
    
* Click ‘Generate Code’ and then click test run.
    
    ![](https://cdn.hashnode.com/res/hashnode/image/upload/v1716347646302/63c2693c-4330-4892-a74f-635f0f912a07.png align="center")
    
* If the data source configuration is correct, a new tab will be opened and a sample report as shown below will be generated.
    
    ![](https://cdn.hashnode.com/res/hashnode/image/upload/v1716347673086/a338a0da-a668-4143-b7e8-05814b294db0.png align="center")
    
* 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
    
    ![](https://cdn.hashnode.com/res/hashnode/image/upload/v1716347862865/fc862935-ea53-46f5-8d0c-f8c4268d17d5.png align="center")
    
* 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
    
    ```xml
    GRANT CREATE ANY DIRECTORY TO <ReportFactory Schema User>;
    ```
    
* Connect to the ReportFactory user and create the directory.
    
    ```xml
        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 arf.support@maathra.com. Thank you for choosing Maathra ReportFactory, and we look forward to supporting your business needs.