Differences

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

--- emis_developer_manual [2023/02/20 22:03] – [[Optional] Various Visual Studio Configuration] ghachey
+++ emis_developer_manual [2024/06/18 01:26] (current) – 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''.
   - 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 167: / 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 186: / Line 196: @@
-==== Databases Setup ====
+==== Application Configuration ====
-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.
+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.
-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.
+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.
-In VS, open the file ''Web.config'' from the ''Pineaples'' project. Two places you need to configure. Locate the following line.
+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)
 <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 206: / 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.
+<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 ====
@@ Line 219: / Line 270: @@
+==== [Optional] Various Visual Studio Configuration ====
+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 ===
+This is probably a useful setting to keep the frontend dependencies updated with the code base.
+{{ :developer-manual:vs-restore-on-project-open.png }}
+=== Tab vs Spaces Setup ===
+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 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 needs to be set for each file type. Developers of Pacific EMIS has agreed on:
+  * 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)
 ==== Troubleshooting Visual Studio Build/Run Errors ====