The SIAPS Program is funded by the U.S. Agency for International Development (USAID) under cooperative agreement AID-OAA-A-11-00021 and implemented by Management Sciences for Health. The information provided on this web site is not official U.S. Government information and does not represent the views or positions of the U.S. Agency for International Development or the U.S. Government.

Disclaimer of warranties and limitation of liability

The e-TB Manager software, documentation and other products, information, materials and services provided by Management Sciences for Health (MSH or Licensor) are provided “as is.” Licensor hereby disclaims all warranties, whether express, implied, statutory or other (including all warranties arising from course of dealing, usage or trade practice), and specifically disclaims all implied warranties of merchantability, fitness for a particular purpose, title and non-infringement. Without limiting the foregoing, licensor makes no warranty of any kind that this software or documentation, or any other licensor or third-party goods, services, technologies or materials (including any software or hardware), or any products or results of the use of any of them, will meet the users’ or other persons' requirements, operate without interruption, achieve any intended result, be compatible or work with any other goods, services, technologies or materials (including any software, hardware, system or network), or be secure, accurate, complete, free of harmful code or error-free. Licensor is not responsible for further development or any future versions of e-TB Manager.

Copyright Management Sciences for Health.

This repository contains the source code of e-TB Manager 3. Please note that this version has not been thoroughly tested yet.

e-TB Manager is a web-based tool for managing all the information needed by national TB control programs. It integrates data across all aspects of TB control, including information on suspects, patients, medicines, laboratory testing, diagnosis, treatment, and outcome.

In order to build e-TB Manager from the source code, you will need the following programs installed:

• Java JDK 11
• Maven 3+

In order to work with client side development, it is highly recommended that you also install the following programs:

• Node 6.17.1
• Gulp 3.8+

Development tools

• A development environment of your choice - Recommended: IntelliJ for server development, and Sublime 3 for client development
• eslint, for client linting

Installation instructions can be found in the site of each one of these programs.

Below is the list of frameworks and libraries used in e-TB Manager.

• Spring boot (currently 1.2.6);
• Spring JPA, using Hibernate;
• Freemarker, as template engine;
• Liquibase, for database initialization;
• Dozer, for object to object mapping;
• Google Guava;

• Twitter Bootstrap 3;
• React framework;
• React-bootstrap, to link react and bootstrap;
• Superagent, for Server requests;
• Underscore;
• Font-awesome 4;

All these frameworks are automatically loaded by the respective building tools (Maven and NPM), so the list is just a reference.

Below is a list of the folders in the root directory of the source code:

• src - The server source code (used by Maven);
• client - The client source code (used by NodeJS);
• resource - Any file that is not part of the source, but it is important to keep them as templates, configuration examples, etc.

These are folders generated by the build tools (not to be included in the git repository:

• target - Folder where the final artifacts are generated (for instance, etbmanager.jar);
• node - Local version of NodeJS installed by Maven and used during the build process;
• node_modules - NodeJS modules installed by NPM and used in the client folder;
• .idea - Created by IntelliJ IDE, if used for development;

These are the main files in the root folder:

• pom.xml - Maven project file;
• gulpfile.js - Gulp project file, responsible for development, testing and build of the client code;
• package.json - List of dependencies used in the client side (required by NPM tool);
• webpack.config.js - Used by webpack tool for UI building and development;
• .jshintrc - Used by jshint for UI validation;
• .gitignore - List of files and folders to be ignored by git;

You need the following tools in order to start development:

• Git
• Java 11
• Maven 3+
• Node 6.17.1
• Gulp 3.8+
• A development environment of your choice (IntelliJ recommended)

The source code is stored in a Git repository, and the current Git URL is:

https://github.com/MSH/eTBmanager-3

To download the code, issue the git command

git clone https://github.com/MSH/eTBmanager-3

You will need a user name and password for that.

Inside the repository, there are two main branches: master and devel. The master contains the stable version, and should be merged with stable versions achieved in the development branch. So, if you want to change the code, move to the devel branch:

git checkout devel

When you finish your changes, perform the following git sequence (as described in the git documentation):

1. Add all changed files to be committed

   git add .

2. Commit the changes providing a good description

   git commit -m "description of the changes"

3. Upload the changes to the remote server

   git push origin development

In order to generate a new version of e-TB Manager from the source code, you must issue the following Maven command:

mvn clean package

The Command above will also generate manifest.json file which will contain all the language and Clint side code in src/main/resouces/static/

This will install all necessary dependencies and generate a new version in target/etbmanager-x.x.x.jar, where x.x.x is the version number.

Before running e-TB Manager, it is necessary to create a text-file called etbmanager.properties containing information about e-TB Manager configuration.

This file is a text-based property file in the format value=key and must be in the same directory of the ebmanager-xxx.jar (or in the working directory, if set).

An example of this file can be found in the resources folder. These are the main properties available:

db.url= # jdbc connection string
db.user= # database user name
db.password= # database password
web.port = # the web server port to use

For now, only two databases are supported:

• MySQL 5.5+ - Recommended when installing in a server computer;
• HSQLDB - Recommended when installing in a desktop computer for off-line and local usage;

Below are examples of connection strings:

db.url = jdbc:mysql://localhost/etbmanager

db.url = jdbc:hsqldb:file:database/etbmanager;default_schema=true

In order to run e-TB Manager, just run it as any other java application:

java -jar etbmanager-xxx.jar

or using Maven

mvn clean package exec:exec

You must provide a configuration file etbmanager.properties, as described in the previous section.

When initialization finishes, open the URL below:

http://localhost:8080/index.html 

or

http://localhost:8080

There is no restriction on the IDE in use, but the recommended one is IDEA IntelliJ.

The build tool uses CheckStyle to guarantee that Java code follows code standards. CheckStyle rules are located in the checkstyle.xml file. To check if your code adheres to the rules, you may use maven for that:

mvn checkstyle:check

IDEA CheckStyle plugin - There is a CheckStyle plugin available, which makes it easier to display the CheckStyle issues.

Once installed, go to Preferences -> Other Setting -> CheckStyle, and include the file checkstyle.xml located in the project root folder.

e-TB Manager client side (browser code) uses npm and gulp as the building tool system. npm is used for dependency management, while gulp is used for running several tasks like the development server, testing the code, system building and much more.

Although not required, a group of tasks are available in gulp to make client side development easier. They are implemented in the gulpfile.js . The main command lines are:

npm run run - Prepare and run the client side on a proxy web server using gulp (the same as running gulp run). This proxy web-server has the following features:

• Provides client files (js, html, css, etc);
• Automatically update browser window when a file is changed;
• Proxy requests to the server-side (the server side must be running);
• Cache JS files in order to make quick rebuild on file changes;

gulp build - Prepare and build all client files and copy them to the folder src\main\resources\static.

gulp test - Run the UI tests (TO BE DONE);

Sublime is a lightweight text editor widely used for Nodes and Javascript development. One of the strenght in Sublime is its plugin system. Although not required, it is recommended to use the following plugins:

• SublimeLinter
• SublimeLinter-contrib-eslint
• Babel
• ColorPicker
• DocBlockr
• LESS
• MarkdownEditing

SublimeLinter is a plugin for Sublime Text 3 that provides a framework for linting code, and SublimeLinter-contrib-eslint provides integration to the eslint tool, in order to provide JavaScript linting. Check how to install them and use them in Sublime.

Inside the source code structure, SublimeLinter-contrib-eslint recognizes files called .eslintrc as the eslint configuration.

It is also necessary to install the following programs, in order to have the plugins working properly:

• eslint
• eslint-plugin-react

Atom editor is another IDE that you can use to edit the client code. Please go to http://atom.io and follow instructions on how to install it.

Server side tests are implemented using JUnit and Spring Boot under the src/test/java folder.

When running test suites, the application will be started. When started in test mode, the application will search for the etbmanager.properties file in the target/test folder.

When executing tests using maven, it will automatically copy a configuration file from resources/test/mysql/etbmanager.properties.

e-TB Manager follows the maven standard way of executing tests:

mvn test

The source will be compiled and all tests will be executed.

JUnit tests are not the only one available - The test suite also contains API call tests and UI tests.