{"id":24111441,"url":"https://github.com/reportvine/kapenta","last_synced_at":"2025-05-13T10:49:25.240Z","repository":{"id":38990301,"uuid":"100724903","full_name":"reportvine/kapenta","owner":"reportvine","description":"Generate RESTful APIs for your Pentaho Reports automatically from a YAML configuration file","archived":false,"fork":false,"pushed_at":"2024-10-25T08:37:03.000Z","size":4008,"stargazers_count":5,"open_issues_count":11,"forks_count":1,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-01-11T02:34:16.573Z","etag":null,"topics":["api-server","java","malawi","pdf","pdf-generator-api","pentaho","reports"],"latest_commit_sha":null,"homepage":"https://nndi.cloud/oss/kapenta/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/reportvine.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2017-08-18T15:18:52.000Z","updated_at":"2024-09-05T20:53:47.000Z","dependencies_parsed_at":"2022-08-25T21:52:33.325Z","dependency_job_id":"86830668-a880-48f5-a726-6b03a209e643","html_url":"https://github.com/reportvine/kapenta","commit_stats":null,"previous_names":["reportvine/kapenta"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reportvine%2Fkapenta","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reportvine%2Fkapenta/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reportvine%2Fkapenta/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reportvine%2Fkapenta/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/reportvine","download_url":"https://codeload.github.com/reportvine/kapenta/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253928428,"owners_count":21985793,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-server","java","malawi","pdf","pdf-generator-api","pentaho","reports"],"created_at":"2025-01-11T02:34:18.129Z","updated_at":"2025-05-13T10:49:25.181Z","avatar_url":"https://github.com/reportvine.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![](https://img.shields.io/github/license/nndi-oss/kapenta.svg)](./LICENSE)\n\nKapenta\n=======\n\nGenerate RESTful APIs for your Pentaho Reports automatically from a YAML configuration file.\n\n## Basic Usage\n\nLet's assume you have designed a report called `customer_report` in Pentaho Report Designer\nand you want to make this report available via an *API*.\n\n\u003e NOTE: Credit Data provides a \"lite\" build of Pentaho Report Designer on the [prd-ce-lite](https://github.com/creditdatamw/prd-ce-lite)\n\u003e repository which is a small download and mostly suitable for use with SQL databases\n \nYou can create this configuration  and save it in a yaml file called `configuration.yml`\n\n```yaml\n# configuration.yml\nhost: localhost\nport: 4567\napiRoot: /api\nreports:\n  - name: Customer Report\n    version: \"1.0.0\"\n    path: /customer_report\n    file: ./customer_report.prpt\n    parameters:\n      - name: customer_id\n        type: Long\n        required: true\n        default: 0\n```\n\nRunning the following command will start a webserver at port 4567\n\n```bash\n$ bin/kapenta server --config configuration.yml --host \"0.0.0.0\" --port 4567\n```\n\nThe API created will have two end-points, one for generating your report.\nExample to generate a report for customer with id #1 we'd have:\n\n`http://localhost:4567/api/customer_report?customer_id=1`\n\nThis by default will result in an html report being generated. The server currently\nsupports three output types for a report: PDF, HTML and TEXT\n\nIn order to get a PDF report - append `.pdf` to the path before adding the query\nparameters or set the `Accept` header to `application/pdf`.\n\nFor example the same request above can be made a pdf by performing the request in a browser:\n\n`http://localhost:4567/api/customer_report.pdf?customer_id=1`\n\nIn order to get a Text report - append `.txt` to the path before adding the query\nparameters or set the `Accept` header to `text/plain`.\n\n**All output is UTF-8 encoded**\n\nAn end-point is generated that allows you to see what parameters are accepted \nby the report.\n\nFor example, you could run the following request: \n\n```bash\n$ curl -G http://localhost:4567/api/customer_report/info\n```\n\nIn this case will give you \n\n```json\n{\n  \"reportName\" : \"Customer Report\",\n  \"version\" : \"1.0.0\",\n  \"parameters\": [\n    { \"name\": \"customer_id\", \"type\": \"Long\", \"default\" : 0, \"required\": true }\n  ]\n}\n```\n\n## Generating Configuration\n\nLet's say you have too many reports you want to expose via an API or you're just too busy to write up the YAML\nconfiguration by hand you can **automagically generate** the YAML configuration using the same binary!\n\nLet's assume you have reports in a directory called `/var/pentaho_reports`. You can use the following\ncommand to generate a YAML file called `my_api.yml` that contains basic configuration for the reports\nin that directory.\n\n\u003e NOTE: The directory must contain valid Pentaho report templates but may also contain other files. The\n\u003e generator only picks up the Pentaho files\n\n```sh\n$ bin/kapenta generate --directory /var/pentaho_reports --output-file my_api.yml  \n```\n\nYou can then use the generated YAML file to run your API and you didn't have to write anything!\n\n```sh\n$ bin/kapenta server --config my_api.yml\n```\n\nThe generated configuration file does not configure backup and authentication - so if you\nneed those features you have to add them in yourself. See the *Advanced Configuration* section, below.\n\n## Advanced Configuration\n\n## Server Configuration\n\nYou can configure the server to bind to a different ip address than `localhost` and\ndifferent port than the default `4567`.\n\nFor example\n\n```yaml\nhost: 192.168.1.45\nport: 8172\n```\n\n## Logging Configuration\n\nThe configuration file also expects a some configuration for logging, the required\nfields for now specify the level and the directory to store log files in.\n\n```yaml\nlogging:\n  rootLevel: INFO\n  directory: ./logs\n```\n\n## Report Backups\n\nIf you want to be able to store a backup of the reports clients/users have generated via the API\nyou can do so via the following configuration.\n\nThe files are saved with the output type that's sent to the requesting clients and are prepended\nwith the timestamp they are generated at using `System.currentTimeMillis()`.\n\nFor example a generated text report for `hello report` would have a backup with name `1483718274331-helloreport.txt`\n\n\u003e **NOTE**: Set the directory to a directory that the user running the process has write permissions to.\n\n```yaml\n# Configuration for backup of generated reports\nbackup:\n  # Where to store the generated reports\n  directory: /var/log\n  # If the directory should have subdirectories for each day\n  rollingBackup: true\n```\n\n### Rolling Backups\n\nRolling backups creates a directory per day and stores the reports in the directory\nwith the date they were generated. The directories are named in `YYYY-MM-DD` format.\n\nFor example: `2017-01-01`\n\n### Configuring Basic Authentication\n\nIn order to add some level of security to the API you can configure HTTP Basic Authentication via\nthe configuration file.\n\n#### Single User authentication\n\n```yaml\nbasicAuth:\n  user:\n    username: foo\n    password: foo123\n```\n\n#### Multiple Users authentication\n\nIn order to allow multiple usernames and passwords to authenticate to the API you can use\nthe `users` key in the basicAuth configuration\n\n```yaml\nbasicAuth:\n  users:\n    - username: foo\n      password: foo123\n    - username: john\n      password: john123\n```\n\n## Building\n\nYou will need a minimum of [Java 21](https://jdk.java.net/) \nand [Maven 3.8](https://maven.apache.org/) to build the project.\n\nThe project uses the [maven assembly plugin](https://maven.apache.org/plugins/maven-assembly-plugin/usage.html) \nto create both a zip and tar archive\nthat contains the compiled application, all it's dependencies and the executable \nscripts; `bin/kapenta.bat` file for Windows and a bash (`bin/kapenta`)\nfile for Linux.\n\n```sh\n$ git clone https://github.com/nndi-oss/kapenta.git\n$ cd kapenta\n$ mvn clean install\n$ mvn assembly:assembly\n```\n\nThe archives will be created in the `target` directory.\n\n## Note on MySQL database drivers\n\nWe use [MariaDB's client library](https://mariadb.com/kb/en/library/client-libraries/) for connecting to mysql databases.\n\n## CONTRIBUTING\n\nSee the [`CONTRIBUTING.md`](CONTRIBUTING.md) file for more information.\n\nShout out to [Credit Data CRB Ltd](https://creditdatamw.com) for handing the project over  for us to maintain.\n\n---\n\nCopyright (c) 2022, Zikani Nyirenda Mwase, NNDI\nCopyright (c) 2017 - 2021, Credit Data CRB Ltd","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freportvine%2Fkapenta","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freportvine%2Fkapenta","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freportvine%2Fkapenta/lists"}