Differences

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

--- emis_developer_manual [2023/02/20 21:49] – [Download and Install the Main Development Tools] 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''.
   - 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.
+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.
+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 }}
+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.
+{{ :developer-manual:task-runner-explorer.png?nolink |}}
+==== Application Configuration ====
+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.
+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.
+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>
+<code xml>
+<appSettings>
+  <add key="server" value="localhost" />
+  <add key="database" value="siemis" />
+  <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 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 ====
+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.
+{{ :developer-manual:vs-run-project.png }}
-TODO
 ==== [Optional] Various Visual Studio Configuration ====
@@ Line 212: / Line 312: @@
   * **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>
-<appSettings>
-  <add key="server" value="localhost" />
-  <add key="database" value="siemis" />
-  <add key="context" value="siemis" />
-  <add key="title" value="FedEMIS Online" />
-  <add key="ReportServerUrl" value="http://localhost:8080/reportserver" />
-</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)
-==== Building 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 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.
-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.
-{{ :developer-manual:vs-run-project.png }}
 ==== Troubleshooting Visual Studio Build/Run Errors ====