Documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== JasperReports Developer Guide ======

While the system can potentially support JasperReports, SQL Reporting Services and others the currently mostly used reporting platform is JasperReports from [[https://community.jaspersoft.com|JasperSoft Community]], a mature reporting platform including the engine, a visual designer and a reports server.

The JasperServer supports a comprehensive RESTful API for integration with other systems and this is what is used by the Pacific EMIS to include professional reports directly into the Pacific EMIS web UI. 

Integration provides: 

  * A single page listing all KEMIS reports in the Jasper server
  * A page listing that subset of reports relating to a particular entity (e.g. Schools, Teachers)
  * A tab on Entities showing reports relating to a single item (e.g. a school, a teacher)
  * Opportunities to embed reports at context-specific places in the user interface. In other words, including any report anywhere.
 
===== Jasper Technologies Installation =====

A developer wanting to work with this would need to:

  * Install the [[https://community.jaspersoft.com/project/jaspersoft-studio|JasperSoft Studio]] on the developer machine
  * Install the [[JasperReports Server|https://community.jaspersoft.com/project/jasperreports-server]] on the developer machine
  * Optionally install the [[JasperReports Server|https://community.jaspersoft.com/project/jasperreports-server]] on the production machine if developer also plans to push reports into production
  * Provide appropriate security for JasperReports Server (i.e. change default username and password at minimum) at least for production development.

===== Download the Pacific EMIS Source Code =====

You should first create a clone of the [[https://github.com/ghachey/pacific-emis-reports|Pacific EMIS Reports repository]] and check it out on your own computer.

===== Jaspersoft Workspace =====

Set your Jaspersoft Studio Workspace to point to the location where all the reports for this project are located. For example, you may have cloned it in ''C:\Uses\Youruser\Development\JaspersoftWorkspace\'' and you would change the workspace to look like the following. You can do this from main menu's ''File - Switch Workspace''.

{{ :developer-manual:jasper-workspace-switch.png?nolink |}}

===== Jaspersoft Set Java Build Path =====

There are a few things to add to the Java build path for things to compile correctly. As shown in the illustration below click on Project Explorer, MyReports and Properties. Then Java Build Path, Libraries and Add External JARs.

  * Install the [[https://docs.microsoft.com/en-us/sql/connect/jdbc/download-microsoft-jdbc-driver-for-sql-server?view=sql-server-ver15|SQL Server JDBC driver]].
  * Font extension (Jar file can be found in the Pacific EMIS Report source code repository)
  * Chart customizer (Jar file can be found in the Pacific EMIS Report source code repository)

{{ :developer-manual:jasper-add-jdbc-driver.png?nolink |}}

===== Jaspersoft Setup Data Adaptors =====

Setup data adaptors for all databases you will be developing for. Example shown below.

{{ :developer-manual:jasperstudio-create-data-adaptors.jpeg?nolink |}}


===== Jaspersoft Setup Servers =====

Setup serversconnections for all databases you will be developing for. Example shown below.

{{ :developer-manual:jasper-servers.png?nolink |}}


===== Jaspersoft Publishing Strategy to JasperServer =====

The adopted publishing strategy for all Pacific EMIS reports is to always override all resources when reports modifications such as improvements or fixes are made. Use local resources for any subreport and link resources for the following which are on the JasperServer in a single place for better re-usability.

  * Images
  * Templates
  * Input controls (parameters)

{{ :developer-manual:jasperserver-publish-strategy-1.png?nolink |}}

To make this mostly automatic you can change the following setting.

{{ ::jasperserver-publish-strategy-2.png?nolink |}}
===== Reports Structure =====

For things to work as designed and expected you will need to follow some simple convention for how you structure your reports. Basically, it should reflect what is shown in the following illustration. That is in MyReports we have a list of country context all in small caps (e.g. fedemis, miemis, siemis, kemis, etc.). Each of those countries have a list of EMIS modules (e.g. Exams, Schools, Teachers, Students, etc.). Those EMIS modules have reports relevant their their respective modules. For example, Schools, contain schools reports. Then each module can potentially have EMIS module instances (e.g. a School, a Teacher, etc.) Those contain reports for individual instances (e.g. a school card report, a teacher profile report). Other reports can for now be organized in any way but may need to be included manually in the UI as oppose to automatically listed in their respective locations. Images and Templates folder simply contain reusable resources like logo and "stylesheets".

{{ :developer-manual:jasper-reports-structure.png?nolink |}}

===== Running and Deploying Reports =====

TODO 

===== Report Parameters =====

The EMIS will attempt to provide the parameters to the Jasper report according to the context from which the report is invoked. For example, when invoking a report from the School folder, displayed inside the School UI, it will pass the current value of schNo. The parameter accepting the school ID **//must//** be named SchoolNo. If this is the only mandatory parameter, the report will be generated without further UI prompt. If other mandatory parameters are defined but not set, a dialog will prompt for these. Similarly, for reports relating to an individual teacher, use the parameter TeacherID to accept the teachers identifier (tID the primary key of TeacherIdentity). 

For reports relating to a set of schools, you may use the parameter names corresponding to those accepted by the School filter. You can find what those are in ''Pineapples.Data -> Models -> SchoolFilter.cs''. You would find out how to name the parameters the same way with other modules (e.g. Teachers, School Accreditations). Example of most wanted parameters for schools could be:

  * SchoolNo
  * SchoolType
  * District
  * Island
  * ElectorateN
  * ElectorateL
  * Authority

In the Schools report page, these parameters will be supplied where possible from the School filter. In this case, the parameters dialog will always be displayed when invoking the report.

In the general reports page, listing all reports, the parameters dialog will always be displayed; no defaults will be provided by the EMIS. 

===== InputControls and Queries =====
 
We are establishing InputControls and queries to provide dropdown lists for parameters associated to the main EMIS code types. If connected to your report, you’ll get a dropdown list for the parameter in both the JasperServer UI and the EMIS UI (when you get a parameter dialog.)

Each Jasper repository contains an InputControls folder to store reusable input controls. Within this there is a ''Lookups'' folder, to store InputControls that provide dropdown lists based on EMIS lookup tables. In the Lookups folder there is a folder Queries, to store the particular SQL relating to that lookup.

The id of the InputControl and the id of the query should match, and should be the same as the name assigned to the lookup in EMIS. These lookup names are seen here (reading ''/api/lookups/collection/core''):

{{ :developer-manual:jasper-inputcontrols-1.png?nolink&400 |}}

and are defined in ''DSLookups.c'' in ''Pineapples.Data''"
‌
<code csharp>
public DSLookups(DB.PineapplesEfContext cxt) : base(cxt)
    {
        lkpCommands = new Dictionary<string, string>();
        lkpCommands.Add("schoolTypes", "SELECT stCode C, stDescription N from TRSchooltypes;");
        lkpCommands.Add("schoolCodes", "SELECT schNo C, schName N FROM Schools;");
        lkpCommands.Add("districts", "SELECT dID C, [dName] N from Districts ORDER BY dName;");
        lkpCommands.Add("authorities", "SELECT authCode C, authName N, authType T from TRAuthorities;");
        lkpCommands.Add("authorityTypes",
                        "SELECT [codeDescription] N, [codeCode] C, codeGroup G from TRAuthorityType;");
        lkpCommands.Add("authorityGovt",
                        "SELECT [codeDescription] N, [codeCode] C from TRAuthorityGovt;");
        lkpCommands.Add("islands", 
                        "SELECT [iName] N, [iCode] C, [iGroup] D, [iOuter] R FROM lkpIslands ORDER BY [iName];");
        lkpCommands.Add("regions", "SELECT [codeCode] C, [codedescription] N FROM lkpRegion ORDER BY [codedescription];");
        lkpCommands.Add("educationLevels", 
                        @"Select codeCode C, codeDescription N, edlMinYear MinY, edlMaxYear MaxY
                            from TREducationLevels ORDER By edlMinYear");
        lkpCommands.Add("educationLevelsAlt",
                        @"Select codeCode C, codeDescription N, edlMinYear MinY, edlMaxYear MaxY
                            from TREducationLevelsAlt ORDER By edlMinYear");
        lkpCommands.Add("educationLevelsAlt2",
                        @"Select codeCode C, codeDescription N, edlMinYear MinY, edlMaxYear MaxY
                            from TREducationLevelsAlt2 ORDER By edlMinYear");
        lkpCommands.Add("educationSectors",
                       @"Select secCode C, secDesc N 
                            from TREducationSectors ORDER By secSort");
</code>

Now these SQL statements that define the lookup can be the SQL set by the query in Inputcontrols/Lookups/Queries in the Jasper repository. Example, dropdown to select Authority Govt. First create the query, matching the name and SQL from DSLookups:

{{ :developer-manual:jasper-inputcontrols-2.png?nolink&400 |}}

{{ :developer-manual:jasper-inputcontrols-3.png?nolink&400 |}}

Now the input control linked to that query:

‌{{ :developer-manual:jasper-inputcontrols-4.png?nolink&400 |}

{{ :developer-manual:jasper-inputcontrols-5.png?nolink&400 |}}

===== Integration with Pacific EMIS =====

Refer to the [[JasperReports Systems Administrator Guide]]