malike / elasticsearch-report-engine

Plugin to generate Reports from Elasticsearch Queries.

• Basic Overview
• Install
• Usage
  • PDF
  • HTML
  • CSV
• Download
• Scheduling
• Contribute
• Code of Conduct
• License

Overview

Once this plugin is installed into elasticsearch search,it exposes the url http://{ip}:9200/_generate, you can run queries on your cluster with the right parameters it would return PDF,HTML or CSV file.

Install

1. Install plugin

sudo bin/elasticsearch-plugin install https://github.com/malike/elasticsearch-report-engine/releases/download/5.4.0/st.malike.elasticsearch.report.engine-5.4.0.zip

2. Grant permissions

3. Folder Structure

Create folders templates and reports in ES_HOME. Store your *.jasper and *.jrxml files in the templates folder and pass the templateName as the template (with the right extension) parameter for HTML and PDF reports.

Usage

PDF

1. PDF Report

The plugin uses Jasper Report as core engine for generating PDF reports. PDF templates can be designed using iReport Designer. This generates a jrmxl file. You can also use the compiled file with the extension jasper.

The plugin generates base64 encoded stream of the PDF report generated once you pass the name of the template file and the query to fetch data from Elasticsearch.

PDF Sample Request

  curl -H "Content-Type:application/json" -XPOST "http://localhost:9201/_generate"  -d '{"format":"PDF","fileName":"TEST_REPORT","index":"reportindex","template":"filename.jrxml","from":0,"size":10,"query":"{term:{description:Transaction}}"}'

Parameters

i. format : Format of Report [Required]
ii. index : Elasticsearch Index [Required]
iii. template : Jasper Report Template [Required]
iv. from : Offset for querying large data [Optional]
v. size : Size for querying large data [Optional]
iv. query : Query to search Elasticsearch index [Optional : Defaults to '*' if nothing is passed]
vi. fileName : File name [Optional]

Generate PDF Response

i. Success

{"status":true,
  "count":1,
  "data": "base 64 encoded string",
  "message":"SUCCESS"
  }

ii. Missing Required Param

  {"status":false,
   "count":0,
   "data": null,
   "message":"MISSING_PARAM"
   }

iii. Report Format Unknown

   {"status":false,
    "count":0,
    "data": null,
    "message":"REPORT_FORMAT_UNKNOWN"
   }

iii. System Error Generating Report

   {"status":false,
    "count":0,
    "data": null,
    "message":"ERROR_GENERATING_REPORT"
   }

Sample PDF

HTML

2. HTML Report

Just like the PDF report,the HTML also uses Jasper Report as core engine for generating reports.

HTML Reports provides an alternative for use cases where reports should not be sent as an attached file.

The generates base64 encoded stream of the HTML report generated. There's also an option to return the HTML string instead of the base64 encoded string. This requires passing returnAs:PLAIN as part of the request JSON.

HTML Sample Request

  curl -H "Content-Type:application/json" -XPOST "http://localhost:9201/_generate"  -d '{"format":"HTML","fileName":"TEST_REPORT","index":"reportindex","template":"filename.jrxml","from":0,"size":10,"query":"{term:{description:Transaction}}"}'

Parameters

i. format : Format of Report [Required]
ii. index : Elasticsearch Index [Required]
iii. template : Jasper Report Template [Required]
iv. from : Offset for querying large data [Optional]
v. size : Size for querying large data [Optional]
iv. query : Query to search Elasticsearch index [Optional : Defaults to '*' if nothing is passed]
vi. fileName : File name [Optional]
vii. returnAs : How you want HTML file returned. Possible values PLAIN and BASE64 [Optional : Defaults to BASE64]

Generate HTML Response

i. Success

 {"status":true,
  "count":1,
  "data": "base 64 encoded string",
  "message":"SUCCESS"
  }

ii. Missing Required Param

  {"status":false,
   "count":0,
   "data": null,
   "message":"MISSING_PARAM"
  }

iii. Report Format Unknown

 {"status":false,
  "count":0,
  "data": null,
  "message":"REPORT_FORMAT_UNKNOWN"
 }

iii. System Error Generating Report

   {"status":false,
    "count":0,
    "data": null,
    "message":"ERROR_GENERATING_REPORT"
   }

Sample HTML

*Note: For HTML reports you want returned as HTML string instead of a base64 encoded string. Send this parameter as part of your default parameters : "returnAs":"PLAIN

CSV

3. CSV Report

Unlike the PDF and HTML reports,the CSV option does not use Jasper Report as core engine for generating reports. Generating a CSV report uses the query and returns a base64 encoded of the file.

CSV Sample Request

    curl -H "Content-Type:application/json" -XPOST "http://localhost:9201/_generate"  -d '{"format":"CSV","fileName":"TEST_REPORT","index":"reportindex","from":0,"size":10,"query":"{term:{description:Transaction}}"}'

Parameters

i. format : Format of Report [Required]
ii. index : Elasticsearch Index [Required]
iii. returnAs : How you want CSV file returned. Possible values PLAIN and BASE64 [Optional : Defaults to BASE64]
iv. from : Offset for querying large data [Optional]
v. size : Size for querying large data [Optional]
iv. query : Query to search Elasticsearch index [Optional : Defaults to '*' if nothing is passed]
vi. fileName : File name [Optional]

CSV Sample Response

i. Success

 {"status":true,
  "count":1,
  "data": "base 64 encoded string",
  "message":"SUCCESS"
  }

ii. Missing Required Param

   {"status":false,
      "count":0,
      "data": null,
      "message":"MISSING_PARAM"
      }

iii. Report Format Unknown

   {"status":false,
      "count":0,
      "data": null,
      "message":"REPORT_FORMAT_UNKNOWN"
      }

iii. System Error Generating Report

   {"status":false,
      "count":0,
      "data": null,
      "message":"ERROR_GENERATING_REPORT"
      }

Sample CSV

*Note: For CSV reports you want returned as comma separated values instead of a base64 encoded string. Send this parameter as part of your default parameters : "returnAs":"PLAIN

Download

Elasticsearch versions supported by this plugin include :

Scheduling

This plugin can work with an alerting system and a custom elasticsearch watcher to send emailed reports to specific contacts. By creating your watcher events in the custom elasticsearch watch, events would be pushed to Apache Kafka once there's a hit, go-kafka-alert listening on Apache Kafka for events would react by emailing embedded HTML reports or attached CSV or PDF reports.

This requires no updates to this plugin but setup and configurations in go-kafka-alert and elasticsearch watcher

Contribute

Contributions are always welcome! Please read the contribution guidelines first.

Code of Conduct

Please read this.

License

GNU General Public License v3.0