aquab/aquabarrier-reports

AquaBarrier Reports API

A REST API for generating PDF and Excel reports from JasperReports templates with SQL Server database connectivity for AquaBarrier project management.

Features

• —✅ Generate PDF and XLSX reports from JRXML templates
• —✅ SQL Server database connectivity with JDBC
• —✅ Automatic image parameter configuration (15 images)
• —✅ Automatic subreport directory configuration
• —✅ Handles passwords with special characters (@ symbol)
• —✅ Auto-compilation of JRXML files on startup
• —✅ Docker containerized (Python + Java)
• —✅ REST API with interactive documentation

Quick Start

1. Prerequisites

• —Docker installed
• —SQL Server database accessible
• —Environment variables configured

2. Configuration

Create a .env file:

DB_HOST=89.116.121.82
DB_PORT=1433
DB_NAME=hs-prod3
DB_USER=sa
DB_PASSWORD=@Qneo5m4f1zl6
APP_HOST=0.0.0.0
APP_PORT=7860

3. Build and Run

# Build Docker image
docker build -t aquabarrier-reports .

# Run container
docker run -d --name aquabarrier-reports -p 7860:7860 --env-file .env aquabarrier-reports

# Check health
curl http://localhost:7860/health

4. Generate a Report

# Generate PDF
curl -X POST "http://localhost:7860/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "report_name": "rental_agreement",
    "parameters": {"BidderId": 1},
    "format": "pdf"
  }' \
  --output report.pdf

# Generate Excel
curl -X POST "http://localhost:7860/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "report_name": "equipment_checklist",
    "parameters": {"BidderId": 1},
    "format": "xlsx"
  }' \
  --output report.xlsx

API Endpoints

Available Reports

1. 1.rental_agreement - Rental agreement with terms and conditions
2. 2.equipment_checklist - Safety checklist with 15 instructional images
3. 3.tnc_subreport - Terms and conditions (subreport)

Project Structure

aquabarrier-reports/
├── app.py                              # FastAPI application
├── requirements.txt                    # Python dependencies
├── .env                                # Database credentials
├── Dockerfile                          # Docker configuration
│
├── JasperStarterWrapper.java           # Custom Java wrapper
├── jasperstarter-wrapper.sh            # Shell wrapper script
│
├── reports/                            # Report templates
│   ├── rental_agreement.jrxml
│   ├── tnc_subreport.jrxml
│   ├── equipment_checklist.jrxml
│   └── Images/                         # 16 PNG images
│
└── jasperstarter-3.7.0-SNAPSHOT/       # JasperStarter installation

Architecture

User Request (HTTP)
    ↓
FastAPI (Python) - REST API
    ↓
Shell Wrapper - Argument conversion
    ↓
Java Wrapper - Report generation
    ↓
JasperReports - Template processing
    ↓
SQL Server - Data retrieval
    ↓
Generated Report (PDF/XLSX)

Key Technologies

• —Python 3.11 - FastAPI web framework
• —Java 8 - JasperReports engine
• —JasperReports 6.x - Report generation
• —SQL Server JDBC - Database connectivity
• —Docker - Containerization

Additional Documentation

• —[API_USAGE_GUIDE.md](API_USAGE_GUIDE.md) - Detailed API usage examples
• —[HOW_IT_WORKS.md](HOW_IT_WORKS.md) - System architecture and implementation details
• —[TESTING_GUIDE.md](TESTING_GUIDE.md) - Testing procedures and examples
• —[REPORT_RENAME_SUMMARY.md](REPORT_RENAME_SUMMARY.md) - Report naming conventions

Docker Commands

# Build
docker build -t aquabarrier-reports .

# Run
docker run -d --name aquabarrier-reports -p 7860:7860 --env-file .env aquabarrier-reports

# Logs
docker logs aquabarrier-reports

# Stop
docker stop aquabarrier-reports

# Remove
docker rm aquabarrier-reports

# Restart
docker restart aquabarrier-reports

Environment Variables

Troubleshooting

Check API Health

curl http://localhost:7860/health

View Logs

docker logs aquabarrier-reports --tail 50

List Available Reports

curl http://localhost:7860/reports

Test Database Connection

The health endpoint shows database configuration status.

Verify Compiled Reports

docker exec aquabarrier-reports ls -la /home/user/compiled_reports/

Features Explained

Automatic Image Configuration

The Java wrapper automatically configures 15 image parameters for the safety checklist report. Users don't need to pass image paths manually.

Automatic Subreport Configuration

The SUBREPORT_DIR parameter is automatically set based on the compiled report location.

Password with @ Symbol

The custom Java wrapper handles passwords starting with @ symbol, which JasperStarter CLI cannot handle.

Report Compilation Caching

JRXML files are compiled once on startup and cached. Recompilation only happens if the source file changes.

Excel Image Rendering

Proper XLSX export configuration ensures images are embedded in Excel files (file size: 19KB → 2.6MB with images).

Performance Notes

• —Report compilation is cached (only recompile if source changes)
• —Single worker mode for thread safety (--workers 1)
• —2-minute timeout for report generation
• —Temp files cleaned up automatically

Security Notes

• —Password stored in environment variable (not in code)
• —Non-root user in Docker container (UID 1000)
• —SQL Server connection uses encrypt=false (should enable in production)
• —Parameters passed via JasperReports (SQL injection protection)

License

Proprietary - HSI Services, Inc.

Support

For issues or questions:

1. 1.Check the health endpoint: curl http://localhost:7860/health
2. 2.Review Docker logs: docker logs aquabarrier-reports
3. 3.Verify environment variables in .env file
4. 4.Test with interactive documentation at /docs

Version

1.0.0 - Production Ready