Differences

This shows you the differences between two versions of the page.

--- emis_developer_manual [2023/02/20 21:47] – [JasperSoft Studio Setup] ghachey
+++ emis_developer_manual [2023/07/06 18:24] (current) – [Loading the Solution into Visual Studio] ghachey
@@ Line 63: / Line 63: @@
 There is no need for an expensive license, the Express edition which is freely available will work fine for most small countries. If you don't have already a commercial license download the free version [[https://www.microsoft.com/en-us/download/details.aspx?id=29062|MS SQL Server Express]]. Any of the files would have the required minimal database engine but might has well download the 64bit full version called //ENU\x64\SQLEXPRADV_x64_ENU.exe//. Double click and follow through the installation. Choosing the default values is a good start and reboot the system when done.
+The following databases distributed with the source code in the folder databases:
+  * **IdentifiesP.bak**: a database that handles the users, permissions and customization of the navigation menus.
+  * **pacificemisdb.bak**: the primary database containing all the tables, views, stored procedures and functions but with no data at all.
+  * **pacificemisdb-withsamplelookups.bak**: the primary database containing all the tables, views, stored procedures and functions with some sample data particularly common lookup data and meta data for basic configuration.
+<note important>The Pacific EMIS is based on a fairly advanced and complex database. It typically requires a fair amount of the knowledge about the inner workings of the system to correctly configure it for specific needs of a country. While the above database will provide a running system (with no data) it would be unlikely ready for deployment into a country without further customization typically done directly in the data and also via our custom per country template technique.</note>
+Restoring a database from a backup is documented [[https://msdn.microsoft.com/en-us/library/ms177429.aspx|here]]. Take note of the names of your new databases and also the name of the server (e.g. LOCALHOST, HOSTNAME\SQLEXPRESS) you will need those next.
 ==== Programming Language ====
@@ Line 97: / Line 107: @@
   - Download and install [[https://git-scm.com/|Git]]
-  - Download and install latest [[https://www.visualstudio.com/en-us/products/visual-studio-community-vs.aspx|Visual Studio]] (better tested with 2019).
+  - Download and install [[https://www.visualstudio.com/en-us/products/visual-studio-community-vs.aspx|Visual Studio]] (better tested with 2019).
-  - Download and install [[https://www.microsoft.com/en-us/sql-server/sql-server-downloads|MS SQL Server Developer]] (currently moving to 2019).
+  - Download and install [[https://www.microsoft.com/en-us/sql-server/sql-server-downloads|MS SQL Server Developer]] (better tested with 2019; at least one developer uses 2022 without issues).
   - Download and install latest [[https://docs.microsoft.com/en-us/sql/ssms/download-sql-server-management-studio-ssms|MS SQL Management Studio]]
-  - Download and install most recent version 16 LTS [[https://nodejs.org/en/|NodeJS]].
+  - Download and install most recent version 16 LTS [[https://nodejs.org/en/|NodeJS]]. A reboot may be necessary if you also install all the build tools through the installer.
   - Install Bower from the command line you can simply ''> npm install -g bower''.
-  - Install Grunt from the command line you can simply ''> npm install -g grunt-cli''. And a local version of grunt seems to be needed to silence an error in Visual Studio. Again from the command line go into the pineapples root folder and issue a ''> npm install grunt --save-dev''
+  - Install Grunt from the command line you can simply ''> npm install -g grunt-cli''.
   - Download and install [[https://www.sourcetreeapp.com/|SourceTree]] (useful for Git).
+<note important>The latest NodeJS could be made to work with some effort. But last time this was tried there was just a bit more pain then value since this is not part of the application but just the development environment. Using the latest of the version 16 branch works without issues.</note>
 ==== Software Configuration Management ====
@@ Line 146: / Line 156: @@
 <note important>When doing the bower install in the Pineapples.Client project you will be faced with a JQuery conflict resolution. It is actually important to select 2.2.4 otherwise the dashboards will be broken. Refer to https://bitbucket.org/softwords/pineapples/issues/1147/many-dashboard-broken-in-latest-build for details</note>
-Then install a location version of grunt and all the dependencies.
+Then a local version of grunt seems to be needed to silence an error in Visual Studio later. Again, from the command line go into the ``pineapples`` root folder (not ``Pineapples.Client``) and issue the following command.
+<code>
+> npm install grunt
+</code>
+Then install a locale version of grunt and all the dependencies in the ``Pineapples.Client``.
 <code>
@@ Line 161: / Line 177: @@
 {{ :developer-manual:vs-external-tool-config.png }}
-You can then verify if VS is actually using the node and npm binaries you think they were by opening **Tools - NuGet Package Manager - Package Manager Console** and typing the following commands and observing the output.
+You can then verify if VS is actually using the node and npm binaries you think they were by opening **Tools - NuGet Package Manager - Package Manager Console** and typing the following commands and observing the output. The version should be the one you installed manually above (and not the one in the screenshot).
 {{ :developer-manual:vs-confirm-node-npm-version.png }}
@@ Line 167: / Line 183: @@
 </note>
-Try to build the solution. At first, this will automatically get VS to start downloading some NuGet dependencies so will take longer the first time around. Once the build works you can try a _build_deploy of the frontend.
+As a one time thing, you need to set/verify the starting project of the solution. Right click on the **Pineapples** project in the **Solution Explorer** and click on **Set as StartUp project**. The ``Pineapples`` project should from now on become bold.
-TODO
+At this point if you followed closely the previous sections you should already be able to right click on the **Solution 'pineapples'** and click **Build Solution**. The first time around this will require the downloading of all the NuGet packages (npm and bower dependencies would have already been pulled, at least on a good working Internet connection). It should build 4 projects without errors.
-==== [Optional] Various Visual Studio Configuration ====
+You should then try running the grunt task _build_deploy as shown below. Run it a couple of times for good measure.
-If you are interested in actual developing some code there are conventions established that must be followed. Here are some configuration you should be.
+{{ :developer-manual:grunt-build-deploy.png }}
-=== Make sure Visual Studio restores latest packages for the frontend on Startup ===
+If you do not yet see the Task Runner Explorer window you can bring it up by right clicking on the file ``Pineapples.Client -> gruntfile.js`` and then clicking on ``Task Runner Explorer`` as shown below.
-This is probably a useful setting to keep the frontend dependencies updated with the code base.
+{{ :developer-manual:task-runner-explorer.png?nolink |}}
-{{ :developer-manual:vs-restore-on-project-open.png }}
-=== Tab vs Spaces Setup ===
+==== Application Configuration ====
-In VS you can set the handling of tabs for each file type. VS will expand the tab to the number of spaces you specify when the file is displayed. So it doesn't matter what tab size you specify, the file will look nicely indented, if you use the VS option to replace tabs with spaces. This will cause inconsistent indentations when reading the file with any other default tab stop. In particular, you'll see strange behavior when the file is displayed in SourceTree.
+The main configuration for the application is the file ''Web.config'' from the ''Pineaples'' project. There are a few things that need to be configured before you can run the application. The relevant parts of the ''Web.config'' configuration file are detailed here.
-The original developers of this project agree to Use Keep Tabs option as shown below for all file types. To do this go into** Tools - Options - Text Editor** settings.
+You will need to setup two databases: the Identity database (i.e. IdentitiesP) and the application's main database (e.g. MIEMIS, SIEMIS, SIEMIS-TEST, KIEMIS). You should have those already in your MS SQL Server as detailed in previous section.
-This needs to be set for each file type. Developers of Pacific EMIS has agreed on:
+Replace ''localhost'' with your server name and SQL server instance name (e.g. MACHINENAME, MACHINENAME\SQLEXPRESS). The appSettings's database needs to be the one you want to work with (e.g. MIEMIS-TEST). The context is not the same as the database but would be the place app name (e.g. miemis, kemis, siemis, fedemis)
-  * C#: 4 spaces
-  * Everything else (CSS/Javascript/TypeScript): 2 spaces
-Below is example of setting up Javascript.
-{{ :developer-manual:vs-tabs-settings.png }}
-CSS would be the same as Javascript except you can turn off the hierarchical indentation.
-{{ :developer-manual:css-indentation-configuration.jpg?nolink |}}
-And then C#.
-{{ :developer-manual:tab-vs-settings-1.png?nolink |}}
-In SourceTree, the built-in diff viewer always expands tabs as 4 spaces. It works best for seeing what “real” differences are between versions to use the option Ignore Whitespace as shown below. Although the change in white space will not be displayed, it will still be regarded by git as a change to the file.
-{{ :developer-manual:tab-vs-settings-2.png?nolink |}}
-Also note these options in Visual Studio under **Edit - Advanced**:
-  * **Tabify Selected Lines** - converts leading spaces to tabs. Respects the tab size setting in **Tools - Options** when making this conversion. It is recommended to run this on files before submitting a commit.
-  * **View White Space** - toggle display spaces and tabs (CTRL-E,S)
-==== Databases Setup ====
-You will need to setup two databases: the application's main database (e.g. MIEMIS, SIEMIS, SIEMIS-TEST, KIEMIS) and the Identify database (i.e. IdentitiesP). Those should be given to you by one of the developers with appropriate knowledge and authority until a sample database and created and available for use by all stored in database folder.
-Restoring a database from a backup is documented [[https://msdn.microsoft.com/en-us/library/ms177429.aspx|here]]. Take note of the names of your new databases and also the name of the server (e.g. LOCALHOST, HOSTNAME\SQLEXPRESS) you will need those next.
-In VS, open the file ''Web.config'' from the ''Pineaples'' project. Two places you need to configure. Locate the following line.
 <code xml>
 <add name="DefaultConnection" connectionString="Data Source=localhost;Initial Catalog=IdentitiesP;...
 </code>
-And replace ''localhost'' with your server name (e.g. MACHINENAME\SQLSERVER2012). Then locate the following lines.
 <code xml>
@@ Line 234: / Line 214: @@
   <add key="context" value="siemis" />
   <add key="title" value="FedEMIS Online" />
+  ...
+</appSettings>
+</code>
+There are other appSettings less critical but important for some functionalities.
+<code xml>
+<appSettings>
+  ...
+  <!-- The report server configuration for the reporting functionality -->
   <add key="ReportServerUrl" value="http://localhost:8080/reportserver" />
+  <add key="jasperUrl" value="http://data.pss.edu.mh:8080/jasperserver" />
+  <add key="jasperUser" value="jasperadmin" />
+  <add key="jasperPass" value="Adm1n2p$$16!" />
+  ...
+  <!-- The location where files are stored on the computer used by a number of features in the system -->
+  <add key="FileDb" value="C:\files\miemis\filedb" />
+  ...
+  <!-- Emailing functionality cnofiguration -->
+  <add key="emailSenderName" value="EMIS Web Administrator" />
+  <add key="emailSenderAddress" value="no-reply@national.doe.fm" />
+  <!-- use the your own email if you want to test receiving systems emails (e.g. errors notifications) -->
+  <add key="emailReceiverAddress" value="ghachey@nuzusys.com" />
+  <!-- use the bc for testing, so that a copy of all outbound emails is sent to this address -->
+  <!--<add key="emailBcc" value="edemisaudit@softwords.com.au" />-->
+  ...
 </appSettings>
 </code>
-And replace ''localhost'' with your own server name (e.g. same as above MACHINENAME\SQLSERVER2012) and ''siemis'' with the name of your database (e.g. fedemis-test). The context is not the same as the database but would be the place app name (e.g. miemis, kemis, siemis, fedemis)
+And finally, for email notifications to work it must be configured to use a email server. Various approaches can be used, perhaps the easiest is to use a Gmail account with an application password.
-==== Building the Solution ====
+<code xml>
+  <system.net>
+    <mailSettings>
+      <!-- settings for email delivery using smtp client
+      will vary according to the sender - refer to sysadmin docs at
+      http://docs.pacific-emis.org/doku.php?id=systems_administrator_manual#setting_up_email-->
+      <!-- Using a Google account is an easy and reliable way.
+           this may require that you "Access for less secure apps"
+           be enabled for the Gmail account used by the NetworkCredential
+           see https://www.google.com/settings/u/1/security/lesssecureapps -->
+      <smtp deliveryMethod="Network">
+        <network host="smtp.gmail.com" port="587"
+                 userName="youremail@gmail.com" password="yourapppassword"
+                 defaultCredentials="false" enableSsl="true" />
+      </smtp>
+    </mailSettings>
+  </system.net>
+</code>
+==== Running the Solution ====
-First, as a one time thing, you need to set the starting project of the solution. Right click on the **Pineapples** project in the **Solution Explorer** and click on **Set as StartUp project**. The Pineapples project should from now on become bold.
+At this point you should be ready to run the system by clicking on the following. Note that below was first set to Google Chrome but it could be started within any browser.
-At this point if you followed closely the previous sections you should already be able to right click on the **Solution 'pineapples'** and click **Build Solution**. The first time around this will require the downloading of all the NuGet packages (npm and bower dependencies would have already been pulled, at least on a good working Internet connection). It should build 4 projects without errors.
+{{ :developer-manual:vs-run-project.png }}
-You should then try running the grunt task _build_deploy as shown below. Run it a couple of times for good measure.
-{{ :developer-manual:grunt-build-deploy.png }}
-At this point you should be ready to run the system by clicking on the following. Note that below was first set to Google Chrome but it could be started within any browser.
+==== [Optional] Various Visual Studio Configuration ====
-{{ :developer-manual:vs-run-project.png }}
+If you are interested in actual developing some code there are conventions established that must be followed. Here are some configuration you should be.
+=== Make sure Visual Studio restores latest packages for the frontend on Startup ===
-==== JasperSoft Studio Setup ====
+This is probably a useful setting to keep the frontend dependencies updated with the code base.
-Most of the reports are done in JasperReports, a cross-platform and database agnostic open source reporting platform similar to Crystal Reports and MS SQL Server Reporting Services. First thing to do it to download the latest version of [[http://community.jaspersoft.com/project/jaspersoft-studio|JasperSoft Studio]] and install it on your computer. Currently the developers are using version 6.4 so it would be a good idea to run the same version to avoid compatibility issues.
+{{ :developer-manual:vs-restore-on-project-open.png }}
-Once installed on the computer the developer should familiarize with the comprehensive user documentation for JasperReports which is available at the same place. After successfully installing JasperSoft Studio and running some basic reports from the user documentation you should be ready to run the Pacific EMIS reports.
+=== Tab vs Spaces Setup ===
-You can access all reports for each adopting country (e.g.FEDEMIS, MIEMIS, SIEMIS, KIEMIS etc.). They are managed just like all the software code into the pineapples Git repository you cloned in previous step [[developer_manual#Software Configuration Management|Software Configuration Management]]. All the reports are committed into the **JaspersoftWorkspace** of the pineapples repository. This means you can simply change the default location of the JaspersoftWorkspace to reflect this directory. Let's say you clone **pineapples** into **C:\** you would simply click on Jaspersoft Studio's **File -> Switch Workspace**
+In VS you can set the handling of tabs for each file type. VS will expand the tab to the number of spaces you specify when the file is displayed. So it doesn't matter what tab size you specify, the file will look nicely indented, if you use the VS option to replace tabs with spaces. This will cause inconsistent indentations when reading the file with any other default tab stop. In particular, you'll see strange behavior when the file is displayed in SourceTree.
-{{ :developer-manual:jasper-workspace-switch.png?nolink |}}
+The original developers of this project agree to Use Keep Tabs option as shown below for all file types. To do this go into** Tools - Options - Text Editor** settings.
-This should automatically get you all the Pacific EMIS reports for all adopting countries right into your reporting development environment.
+This needs to be set for each file type. Developers of Pacific EMIS has agreed on:
-Next you will need to make sure you have a database driver capable of talking to the MS SQL Server. This can be downloaded [[https://www.microsoft.com/en-us/download/details.aspx?displaylang=en&id=11774|here]] or simple search for "MS SQL Server JDBC Driver Download" if the link gets broken. Unzip this directory somewhere in your computer (e.g. C:\Program Files\) and locate a file called **sqljdbc42.jar**. This is the file you will need to add into your project's referenced libraries. You can do this by right clicking the project **MyReports** from your **Project Explorer** and click **Properties**. Add the Jar file as shown in the following illustration.
+  * C#: 4 spaces
+  * Everything else (CSS/Javascript/TypeScript): 2 spaces
-{{ :developer-manual:jasper-add-jdbc-driver.png?nolink |}}
+Below is example of setting up Javascript.
-TODO
+{{ :developer-manual:vs-tabs-settings.png }}
-  * Create the datasource for one database (same for others)
+CSS would be the same as Javascript except you can turn off the hierarchical indentation.
-  * Open an example report and run it
-  * Discuss standards to follow (all reports should be mostly replicated across all adopting countries, custom styling per countries, etc.)
+{{ :developer-manual:css-indentation-configuration.jpg?nolink |}}
+And then C#.
+{{ :developer-manual:tab-vs-settings-1.png?nolink |}}
+In SourceTree, the built-in diff viewer always expands tabs as 4 spaces. It works best for seeing what “real” differences are between versions to use the option Ignore Whitespace as shown below. Although the change in white space will not be displayed, it will still be regarded by git as a change to the file.
+{{ :developer-manual:tab-vs-settings-2.png?nolink |}}
+Also note these options in Visual Studio under **Edit - Advanced**:
+  * **Tabify Selected Lines** - converts leading spaces to tabs. Respects the tab size setting in **Tools - Options** when making this conversion. It is recommended to run this on files before submitting a commit.
+  * **View White Space** - toggle display spaces and tabs (CTRL-E,S)
 ==== Troubleshooting Visual Studio Build/Run Errors ====