Open Hospital 1.14.2 - Administrator’s Guide

Table of Contents

Open Hospital
1 Introduction
2 Installation
3 Configuration
4 Reports
5 Installing Open Hospital 1.14.2 in Eclipse EE
- 5.1 Run the Project
6 Update Open Hospital
7 Support
8 License

Informatici Senza Frontiere Onlus, 2022
Administrator’s Guide, © 2023 by Informatici Senza Frontiere Onlus
Policies is made available under a Creative Commons Attribution-ShareAlike 4.0 International License: https://creativecommons.org/licenses/by-sa/4.0//.

Open Hospital

1 Introduction

OH - Open Hospital (https://www.open-hospital.org/) is a free and open-source Electronic Health Record (EHR) software application. Open Hospital is deployed as a desktop application that can be used in a standalone, single-user mode (PORTABLE mode) or in a client/server network configuration (CLIENT mode), where multiple clients and users connect to the same database server.

Open Hospital is developed in Java and it is based on open-source tools and libraries; it runs on any computer, requires low resources, and is designed to work without an internet connection.

Open Hospital is the first of a set of software applications that ISF^[1] has developed to support the information management and the activities of hospitals and health centers in the simplest manner possible, by providing tools for the administrative operations (like registering patients, managing laboratory analysis and pharmaceutical stocks) and to produce detailed statistics and reports. It was first deployed in 2006 at the St. Luke Hospital in Angal (Uganda) and it is now used in dozens of different locations around the world.

1.1 Main Features

OH - Open Hospital features include:

Pharmacy management
Laboratory management
OPD management
Patient admission and discharge management
Pregnancy management
Malnutrition control management
Vaccines database
Patient billing support
Therapy management
Appointment scheduling
Internal communication
Statistics and printing

For a detailed description of these features please refer to the Open Hospital User’s Guide.

1.2 Hardware requirements

Minimum hardware requirements for running OH:

PC / Notebook with dual-core CPU
2 Gb RAM (4 Gb recommended)
4 Gb free hard disk space (8 Gb recommended)
Network adapter (for client/server configuration)

These specifications are for the OH application only; database server specifications may vary accordingly to the different use cases.

1.3 Software requirements

Minimum Operating System version required for running OH:

Windows 7 (Windows 10/11 recommended)
Ubuntu 18.04 (Ubuntu 22.04 recommended)

32bit (i686) and 64bit (x86_64) architectures are supported: 64bit architecture is recommended.

1.5 Download

Open Hospital official releases can be downloaded from GitHub: https://github.com/informatici/openhospital/releases/latest

More information can be found on the Open Hospital website: https://www.open-hospital.org/download

1.6 Unpack

Note	Do not double-click on the oh.bat startup script without unzipping the package first!

A compressed archive can be opened on most operating systems by just double-clicking on it. In this way, the archive is just opened, but not uncompressed.

In order to correctly run OH you need to unzip (uncompress) the downloaded package in a folder of your choice.

To uncompress the package: Right-click on the package → Extract all/here

Alternative method: uncompress package from the command line

on Linux:

tar zxvf OpenHospital-v[VERSION]-linux_[ARCH]-[portable].tgz # portable version
unzip x OpenHospital-v[VERSION]-linux_multiarch.zip # multiarch client version

on Windows:

unzip OpenHospital-v[VERSION]-windows_[ARCH]-[portable].zip # portable version
unzip OpenHospital-v[VERSION]-multiarch-client.zip # multiarch client version

After uncompressing the package, browse to the extracted directory (example given for version 1.14.2):

on Linux:

cd /home/OH/OpenHospital-v1.14.2

on Windows:

cd C:\Users\OH\OpenHospital-v1.14.2

Note	You need read/write permission on the selected folder.

Note	Do not run OH by double-clicking on the oh.bat startup script without unzipping the package first!

1.7 Documentation

In the following chapters, all the information needed to install, configure, deploy, run and maintain an Open Hospital installation is presented, including procedures on how to enable and disable features as well as manage users and groups in a multi-user environment. More information can be found on the Open Hospital website https://www.open-hospital.org/documentation.

Note	The information needed to use the OH software is not included in this manual; please refer to the Open Hospital User’s Guide.

2 Installation

Open Hospital is a client application that can be used in three different ways:

2.1 OH - CLIENT mode: multi-computer setup, with a central database (requires some IT knowledge)
2.2 OH - PORTABLE mode: single computer setup, with the database on the same computer (click and run)
2.3 OH - SERVER mode (portable): multi-computer setup, with the central database created by the Open Hospital script (click and run)

Tip	PORTABLE mode can be also used to test the application.

2.1 OH - CLIENT mode

In this mode, the application will need a Server with a DBMS^[2] to store the data.

The free and open-source MariaDB^[3] is the preferred database server.

The typical client/server, networked (LAN) configuration is shown in the following figure:

The Administrator/Installer tasks are hereby listed:

Server
- Download the Open Hospital package for the selected Operating System (see Prerequisites)
- Unpack the downloaded package on the server machine by uncompressing the archive in a folder of your choice
- Install and configure MariaDB/MySQL on the server/computer that will act as the database server
- Create the database through the execution of a script found in the sql/ folder
- Test and run the application using the 'localhost' setting
Clients
- Unpack the downloaded package on a client machine in a folder of your choice
- Configure and run the application to point to the database server using the hostname or the IP address
- Copy the newly configured package on every client

2.1.1 Prerequisites - Software compatibility matrix

Before starting, check the following software compatibility matrix to verify the external software versions needed to run Open Hospital and the current available extended features for every version, architecture, and operating system. ./OH_software_compatibility_matrix.adoc

2.1.2 Java Runtime Environment (JRE)

Depending on the operating system, there are different ways to install the Java Runtime Environment (JRE). The oh.sh / oh.bat scripts can be used to download and install the latest JRE available; it is also possible to install it manually, following the specific instructions for the operating system being used.

Note	See OH Software Compatibility Matrix to identify the correct Java version.

2.1.3 Database Server

Depending on the operating system, there are several software tools to install and manage a MariaDB/MySQL database server. In most cases just a standard installation package of the software is needed, paying attention to configuration options during the installation process.

Note	See OH Software Compatibility Matrix to identify the correct MariaDB / MySQL version.

Note	MariaDB is the preferred alternative for the DBMS.

2.1.3.1 MariaDB/MySQL - Server installation

Please refer to the latest MariaDB/MySQL Server online documentation for download^[4] and installation^[5] information while using this document.

on a Linux machine: during the installation, a “root” password must be defined; it is very important to choose it carefully and to keep it safe.

on a Windows machine: launch the installation and pay attention to the following steps:

Custom Setup
Install all components except Development Components
Select Modify password for database user 'root', choose the root password, and keep it safe
Select Enable access from remote machines for 'root' user
Select UTF8 as the default charset for Best Support For Multilingualism
Select Install as service
Select Enable networking and take note of the selected Port Number

Note	MariaDB installer does not include the bin directory in the Windows PATH environment variable; it must be added manually to the Windows system variable PATH.

To check if the server is active and running, open a terminal window (command prompt) and type the following command:

# mysql –u root -p

Enter password:

The terminal should reply with the MySQL client command line prompt:

MariaDB>

The prompt means that a successful connection to the database server instance has been established.

Note

If the terminal does not reply as above most probably during installation the Include Bin Directory in Windows PATH option was not selected and therefore Windows can not find the mysql command. If this is the case add the path manually by searching "system variables" in the Control Panel or append the full path to the "mysql" command (e.g., "C:\Program Files\MySQL\MySQL Server 5.0\bin\mysql" [with the quotes]). Another option is to uninstall and reinstall MySQL with the Include option selected.

2.1.3.2 MariaDB/MySQL - Configuration

Please use the following configuration values for MariaDB/MySQL server in my.cnf config file. Values can be adjusted and adapted to the hardware resources available. Config file can be my.ini or my.cnf; default for Windows MariaDB is my.ini located at "C:\Program Files\MariaDB-[VERSION]\data\"

#
# Configuration to be inserted below last row of [mysqld] section
#
sql_mode=STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION
max_allowed_packet = 4M # must match the value used on clients for DICOM_SIZE
skip-external-locking
key_buffer_size = 16M
thread_cache_size = 64
lower_case_table_names = 1
explicit_defaults_for_timestamp = OFF
table_open_cache = 64
tmp_table_size = 16M
read_buffer_size = 256K
read_rnd_buffer_size = 512K
join_buffer_size = 2M
sort_buffer_size = 2M
myisam_sort_buffer_size = 8M

[mysqldump]
quick
max_allowed_packet = 16M

[mysql]
no-auto-rehash

[isamchk]
key_buffer = 16M
sort_buffer_size = 16M
read_buffer = 2M
write_buffer = 2M

[myisamchk]
key_buffer = 16M
sort_buffer_size = 16M
read_buffer = 2M
write_buffer = 2M

2.1.3.3 MariaDB/MySQL - Networking

If deployed in a client-server, networked configuration, the database server must be configured to listen on the network interface connected to the local LAN; this can be achieved by editing the MariaDB/MySQL’s config file, my.cnf, and setting the "bind-address" parameter. For example, if you want the database server to listen on all the available network interfaces / IP addresses:

Change:

# Instead of skip-networking the default is now to listen only on
# localhost which is more compatible and is not less secure.
bind-address = 127.0.0.1

To:

# Instead of skip-networking the default is now to listen only on
# localhost which is more compatible and is not less secure.
bind-address = 0.0.0.0

In this way, the database server listens on any IP address (0.0.0.0) configured on the server and can serve the connecting clients.

It is also possible to specify a specific IP address, e.g:

bind-address = 192.168.1.100

2.1.4 OH - Database creation

To create the Open Hospital database, a MySQL client and a set of SQL script files found under the sql/ folder are needed.

On a Microsoft Windows® system, MySQL Workbench® can be used as a client to connect to the database server and perform the needed tasks, while on Linux based systems the MySQL Administrator and MySQL Query Browser tools can be used.

The suggested approach is to use the command-line MariaDB/MySQL client which uses the same commands and syntax for every platform.

Open a terminal and navigate to the sql/ folder (e.g.):

C:\WINDOWS> cd C:\Users\OH\OpenHospital-v1.14.2\sql

C:\Users\OH\OpenHospital-v1.14.2\sql

and run the following command to connect to the database server (e.g.):

C:\Users\OH\OpenHospital-v1.14.2\sql> mysql -u root -p [-h hostname/ip address]
Enter password: *****

using the ‘root’ password chosen during the installation process. The terminal should reply with the MariaDB client command line prompt:

Welcome to the MariaDB monitor.  Commands end with ; or \g.
Your MariaDB connection id is 13
Server version: 10.6.11-MariaDB MariaDB Server

Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

MariaDB [(none)]>

we are now ready to create the database user (isf) with a password, the main OH database (oh) and grant the necessary permissions with the following SQL commands:

MariaDB> CREATE DATABASE oh CHARACTER SET utf8;
	 CREATE USER 'isf'@'localhost' IDENTIFIED BY 'isf123';
	 CREATE USER 'isf'@'%' IDENTIFIED BY 'isf123';
	 GRANT ALL PRIVILEGES ON oh.* TO 'isf'@'localhost';
	 GRANT ALL PRIVILEGES ON oh.* TO 'isf'@'%';
MariaDB> FLUSH PRIVILEGES;

Note	"isf123" is used here as the default password. Change it for production setup!

To check if the database has been correctly created, enter the following command:

MariaDB> show databases;
+--------------------+
| Database           |
+--------------------+
| information_schema |
| mysql              |
| oh                 |
| performance_schema |
+--------------------+

The next step is to select the created database and execute the main SQL database creation script with the command:

MariaDB> use oh; source create_all_en.sql

Note	The data can be installed in different languages by using the related "create_all_xx.sql" file or with demo data using the "create_all_demo.sql" file (English only).

Note	If the error message "ERROR 1148 (42000): The used command is not allowed with this MySQL version" appears the "local infile" command must be enabled on the client by logging in again and specifying the "--local-infile=1" parameter after the "-p"; thus "mysql -u root -p --local-infile=1".

The SQL script creates the OH database structure and populates it with default data.

The ‘isf’ user, different from the ‘root’ one, is the user that the Open Hospital software uses to connect to the database and its password must be changed immediately with the command:

MariaDB> SET PASSWORD FOR 'isf'@'%' = PASSWORD('new-password-here');

Query OK, 1 row affected (0.00 sec)

Rows matched: 1 Changed: 1 Warnings: 0

And then:

MariaDB> FLUSH PRIVILEGES;

Query OK, 0 rows affected (0.00 sec)

MariaDB> quit;

Note	Remember to set the updated database password also in the Open Hospital configuration files and startup scripts oh.sh / oh.ps1.

2.1.5 OH - CLIENT configuration

To set up the database connection for Open Hospital, edit and configure the database settings in the oh.sh / oh.ps1 startup scripts.

Database settings are:

the IP address of the MariaDB/MySQL database server hosting the Open Hospital database. Replace “localhost” with the server IP address (e.g., 192.168.1.100)
the TCP Port Number of the database server - default is “3306"
the Database name of the OH installation - default is "oh"
the Database user of the OH database - default is "isf"
the Database password associated with the user

Please set them according to the values specified in the installation phase:

in oh.sh / oh.ps1 scripts

$script:MYSQL_SERVER="127.0.0.1"
$script:MYSQL_PORT=3306
$script:MYSQL_ROOT_PW="tmp2021oh111"
$script:DATABASE_NAME="oh"
$script:DATABASE_USER="isf"
$script:DATABASE_PASSWORD="isf123"

Note	"isf123" is used here as the default password. Change it for production setup!

After you can generate the config files: on Linux execute oh.sh -g, on Windows launch oh.bat and choose the option g.

Alternative method: you can first generate the config files with the -g and after directly modify the database.properties and log4j2-spring.properties configuration files, located in the oh/rsc/ resource folder, without generating them every time.

Please set them according to the values specified in the installation phase:

in database.properties config file

jdbc.url=jdbc:mysql://127.0.0.1:3306/oh
jdbc.username=isf
jdbc.password=isf123

in log4j2-spring.properties config file

appender.jdbc.connectionSource.connectionString = mysql://127.0.0.1:3306/oh?autoReconnect=true
appender.jdbc.connectionSource.userName = isf
appender.jdbc.connectionSource.password = isf123

Note	These settings are required for every Open Hospital installation/client.

More information on these files can be found in the 3. Configuration section.

2.1.6 OH - Startup and run

The Open Hospital software is now ready to be run by executing the proper launcher command:

on a Linux machine: oh.sh -C (CLIENT mode)
on a Windows machine: oh.bat (Select CLIENT mode from the interactive menu)

If everything is configured correctly, the Open Hospital main splash screen is presented:

And then the main Menu:

It is possible to create a shortcut (link) to the executable script on the desktop, in the Programs Menu or wherever is useful by using the provided icon “oh.ico” that is found in the package.

On Linux, it might be necessary to set the correct permissions to the oh.sh script:

chmod 755 ./oh.sh

Note	Remember to review your setup in the Open Hospital configuration files and startup scripts oh.sh / oh.ps1.

2.2 OH - PORTABLE mode

Open Hospital is a Java software program and it is portable by definition. The PORTABLE mode described in this chapter refers to the possibility of using OH as a self-contained package that includes Java, MariaDB/MySQL Server and all the data, without requiring any software installation. The package can be used on a single computer and used everywhere just by copying a folder - even onto an USB stick - carrying together all the saved data.

Pre-configured "Portable" packages are available for Windows and Linux; see the Download section for more details.

Since the JRE and MariaDB/MySQL are not platform-independent and are provided in different versions and architectures, there exists:

Open Hospital - portable for Linux platforms (embedding Java JRE and MariaDB for Linux, 32 or 64bit)
Open Hospital - portable for Windows platforms (embedding Java JRE and MariaDB for Windows, 32 or 64bit)

Once the required version is downloaded, the application can be started by launching the script inside the package:

oh.sh in the Linux version
oh.bat in the Windows version

No other configuration is needed. Additional options can be shown by executing:

on Linux: oh.sh -h
on Windows: oh.bat and choose among the available options. See oh.bat -h for legacy mode help.

Note	To use Open Hospital in PORTABLE mode for Linux from a USB key it is required that the file permissions in the archive remain unchanged once extracted, otherwise the launcher cannot launch or use the application in an appropriate manner.

Note

Important: the PORTABLE mode is meant to try or test the software or to be used in a facility (like a dispensary) where only a single computer is available. If the facility is large and more clients/operators need to work on the same data, the full installation (client/server) in a networked architecture is recommended.

https://raw.githubusercontent.com/informatici/openhospital/master/oh-bundle/OH-README.md

2.3 OH - SERVER mode (portable)

Open Hospital can be launched in SERVER (portable) mode. SERVER mode launches a local instance of the database server and listens for connections from other clients. This mode is useful to test/simulate a client/server configuration or networked environment; it is not suggested for production setup. To setup a complete client / server configuration, refer to chapter 2.1.3 - Database Server

2.4 Backup & Restore

Backup of the Open Hospital database can be performed in several ways.

Note	The easiest way is to use the provided scripts: on Linux execute oh.sh -e, on Windows launch oh.bat and choose the option e.

Restoring the Open Hospital database can also be performed in several ways.

Note	The easiest way is to use the provided scripts: on Linux execute oh.sh -e, on Windows launch oh.bat and choose the option e.

2.4.1 Backup of database (alternative with MySQL Workbench®)

There are several ways to back up and restore data with MySQL. The recommended method is to use a common MySQL client such as MySQL Workbench®:

Click on the Administration tab on the left side of the Navigator Panel
Click on Data Export option
Select the oh schema
Select the required option from the dropdown below the tables list as required (the suggested option is Dump Structure and Data)
Click on Export to Self-Contained File
Adjust output file location as needed
Select Create Dump in a Single Transaction checkbox
Select Include Create Schema checkbox
Click on the Advanced Options button and scroll down to the Inserts panel (see the second image below):
1. Select complete-insert checkbox
2. Uncheck extended-insert checkbox
3. Return to the main panel
Select the Start Export button

Advanced Options image:

2.4.2 Restore of database (alternative with MySQL Workbench®)

To restore database data with MySQL Workbench®:

Under Server Administration on the Home window select the server instance onto which the data will be restored (Create New Server Instance if doing it the first time).
Click on Manage Import/Export
Click on Data Import/Restore on the left side of the screen.
Select Import from Self-Contained File radio button (right side of the screen)
Select the path and the name of the restore sql file.
Click the Start Import button at the right bottom corner of the window.

2.4.3 Backup of OH code and settings

Backup of the Open Hospital code and settings can be performed by saving the "oh" folder (configuration files are found under the "oh/rsc" folder).

Backup of the client data files, useful for "PORTABLE" mode, can be performed by saving/copying the "data" folder (including all subfolders) found under the main OH installation path

2.5 Folders and directory structure

Open Hospital has a folder tree hierarchy which is shown here, where <version> is replaced with the current Open Hospital version, <operating_system> with windows or linux and <arch> with the OS architecture (32 or 64bit):

OpenHospital-<version>-<operating_system>_<arch>-<client|portable>/
bundle – language files
doc – Open Hospital documentation
lib – Java libraries needed to run the software
oh – Open Hospital application
oh/bin – Open Hospital binaries (compiled software)
oh/rpt_base – JasperReports® reports used by Open Hospital
oh/rpt_base/PDF – Reports defined in oh/rpt_base generated by Open Hospital in PDF format
oh/rpt_stat – JasperReports® reports used by Open Hospital in section Statistics
oh/rpt_stat/PDF – Reports defined in oh/rpt_stat generated by Open Hospital in PDF format
oh/rpt_extra – JasperReports® reports defined by the user
oh/rpt_extra/PDF – Reports defined in oh/rpt_extra generated in PDF format
oh/rsc – resources of Open Hospital, as configuration files and other related files
oh/rsc/icons – icons used in Open Hospital for windows and buttons
oh/rsc/images – images used in Open Hospital
data – Open Hospital local data and configuration
data/conf – Database server configuration files
data/db – Database files (PORTABLE mode)
data/logs – Log files
data/dicom – Image files
data/dump – Database dumps/backups
data/photo – Patients photos
sql – Database creation scripts
sql/extra – SQL scripts for custom / experimental / temporary features
tmp – Temporary files

These folders may be organized differently depending on the version of the software or the architecture of the operating system.

Depending on the chosen operating system and architecture, the needed external applications and libraries (like MySQL/MariaDB and Java JRE) will be present also:

zulu11.<version>-<operating_system><arch>/ - Java Virtual Machine
mariadb-<version>-<arch>/ or _mysql-<version>-<arch>-<build>/ - MySQL Server or MariaDB Server

2.6 Appearance

Open Hospital’s main menu appearance can be customized by adding a logo of choice. To test the feature, rename the image file logo_hospital_example.png found in the oh/rsc/images folder to logo_hospital.png:

The custom logo has to be a 100x100 pixel png image file.

3 Configuration

Configuration of the local Open Hospital instance (CLIENT and PORTABLE mode) is set in the configuration files called “properties files”. The following properties files are found in the oh/rsc subfolder:

database.properties – Open Hospital database connection
dicom.properties – Imaging viewer module options
examination.properties – contains the settings for the ‘examination’ module
log4j2-spring.properties – Logging system and paths
settings.properties – Open Hospital options and settings
sms.properties – SMS Manager module
telemetry.properties – Telemetry module settings
txtPrinter.properties – Text printing system
xmpp.properties – Xmpp Server configuration
default_credentials.properties – contains the default credentials

Furthermore, additional configurations files (not meant to be modified by the user) are:

resolutions.xml – stores locally the information about webcams
version.properties – contains the current Open Hospital version

The properties files are related only to the local instance of Open Hospital; different instances may use specific OH configurations with custom properties files. The properties files can be generated automatically from the packaged .dist files by editing the configuration options available in the startup scripts oh.sh / oh.ps1 and launching OH. The properties files can also be modified manually using a text editor.

Note	Any change to these files requires an application restart to apply the modified settings.

Note	The properties files can be automatically generated/overwritten at any Open Hospital startup, by setting the WRITE_CONFIG_FILES option to "on" in the oh.sh / oh.ps1 scripts.

The following chapters will describe these properties files and their features in detail.

3.1 settings.properties

Open Hospital general configuration is set in the settings.properties file. The default configuration is available in the settings.properties.dist file:

###########################################
# This file contains Open Hospital settings
###########################################
# external settings
MODE=OH_MODE
DEMODATA=off

# experimental settings
APISERVER=off

# internal settings, modules, directories
LANGUAGE=OH_LANGUAGE
SINGLEUSER=YES_OR_NO
DEBUG=no
DOC_DIR=OH_DOC_DIR
PATIENTPHOTOSTORAGE=PHOTO_DIR
INTERNALVIEWER=yes
SMSENABLED=no
VIDEOMODULEENABLED=yes
XMPPMODULEENABLED=no
PARAMSURL=https://conf.open-hospital.org/oh-conf.json

# application settings
ENHANCEDSEARCH=no
INTERNALPHARMACIES=yes
LABEXTENDED=yes
LABMULTIPLEINSERT=yes
MATERNITYRESTARTINJUNE=no
MERGEFUNCTION=yes
OPDEXTENDED=yes
PATIENTEXTENDED=yes
PATIENTVACCINEEXTENDED=yes

# GUI settings
MAINMENUALWAYSONTOP=no

# accounting
ALLOWMULTIPLEOPENEDBILL=yes
ALLOWPRINTOPENEDBILL=yes
BILLSREPORT=BillsReport
BILLSREPORTMONTHLY=BillsReportMonthly
BILLSREPORTPENDING=BillsReportPending
PATIENTBILL=PatientBill
PATIENTBILLGROUPED=PatientBillGrouped
PATIENTBILLSTATEMENT=PatientBillStatement
RECEIPTPRINTER=yes

# pharmacy
AUTOMATICLOT_IN=no
AUTOMATICLOT_OUT=no
AUTOMATICLOTWARD_TOWARD=no
LOTWITHCOST=yes
PHARMACEUTICALORDER=PharmaceuticalOrder
PHARMACEUTICALSTOCK=PharmaceuticalStock_ver4
PHARMACEUTICALSTOCKLOT=PharmaceuticalStock_ver5
PHARMACEUTICALAMC=PharmaceuticalAMC

# dicom / imaging settings
DICOMMODULEENABLED=yes
DICOMTHUMBNAILS=yes

# reports
ADMCHART=patient_adm_chart
DISCHART=patient_dis_chart
EXAMINATIONCHART=patient_examination
OPDCHART=patient_opd_chart
PATIENTSHEET=patient_clinical_sheet_ver3
VISITSHEET=WardVisits

# security
SESSIONTIMEOUT=5
STRONGPASSWORD=yes
STRONGLENGTH=6
USERSLISTLOGIN=no
PASSWORDTRIES=5
PASSWORDLOCKTIME=60
PASSWORDIDLE=365

# telemetry
TELEMETRYENABLED=yes

Every line is composed of a KEY and a value:

KEY=value

Values can be:

Boolean: yes | no or true | false
String: usually a filename or a country code (ISO 3166-1)

Use the provided startup scripts in order to automatically generate the settings.properties file from the corresponding .dist file; after generation, optionally adjust the KEY/value pair as explained in the following sections.

3.1.1 LANGUAGE

The following table shows the allowed values for the OH_LANGUAGE variable:

Key	Default Value	Allowed Values
LANGUAGE	en	ar, de, en, es, fr, it, pt, sw, zh_CN

Open Hospital is available in nine different languages, identified by the international country code:

ar – Arabic
de - German
en – English
es – Spanish
fr – French
it – Italian
pt – Portuguese
sw – Swahili
zh_CN - simplified Chinese

To change the language used in the application edit settings.properties and change the value of this key. If an unknown value is set, the local computer language is applied.

Note	An application restart is required to apply the modified setting.

Note	The language (OH_LANGUAGE) can be automatically set by using the provided oh.sh / oh.ps1 scripts.

3.1.2 SINGLEUSER

The following table shows the default value and the allowed ones:

Key	Default Value	Allowed Values
SINGLEUSER	yes	yes, no

Open Hospital is designed to support multi-user usage. This means that it is possible to define different users, arrange them by group and set different rights in application usage; for instance, a user “receptionist” may be able to register a new patient but not to prescribe a therapy.

Open Hospital has a predefined user called “admin” that has access rights to all the features of the application. When SINGLEUSER is set to YES (default) the program starts with this user and all the features are available.

If SINGLEUSER is set to NO the following login window appears when the program is started:

Note	See 3.1.36 USERSLISTLOGIN in this document to change the login mode.

The default password for the “admin” user is “admin”. After typing this password in the white field and pressing Submit, the main Menu with the functions are enabled.

Once logged in as the “admin” user defining additional users and/or groups is possible (see the Users & Groups chapter in the User’s Guide), or just continue with a simple form of data protection.

Note	The setting is client-side specific, this means that the login can be disabled on a specific client, but logons will still be required on other clients, with the same defined user and group.

Warning

Data security must never be left solely to the application but it must include proper network architecture and a rigid configuration of the clients.

3.1.3 AUTOMATICLOT

The following table shows the default value and the alternatives for lot management:

Key	Default Value	Valid Values
AUTOMATICLOT_IN	no	yes, no
AUTOMATICLOT_OUT	no	yes, no
AUTOMATICLOTWARD_TOWARD	no	yes, no

Open Hospital allows for automatic management of lots in the main pharmacy. This means that it is possible to work in the pharmacy without taking care of lot definitions in loading the store and just specify preparation and expiring date for each charging movement (see 4.2.2.2 Insert stock charging movement in the User’s Guide).

For discharging movement, the lot is automatically calculated according to the nearest expiring date of lots (FEFO - First Expiring First Out). If the quantity to discharge is larger than the quantity of the first selected lot, more than one discharging operation can be generated.

AUTOMATIC LOTS MANAGEMENT is split into two different settings for charging and discharging the main pharmacy and managing lots also in the wards. In this way, more control is given to the user that may want to provide all the lots' details in charging operations but ask the application to automatically discharge the nearest expiring ones (FEFO). Similarly, in wards (see 4.3 Pharmaceuticals Stock Ward in the User’s Guide) the user may decide to manage lots manually or to ask the application to do it automatically.

With AUTOMATICLOT_IN = YES the application generates a lot number automatically and only asks for an expiration date (mandatory). By default, AUTOMATICLOT_IN is set to NO. It is possible to change the value at any time.

With AUTOMATICLOT_OUT = YES the application discharges automatically the nearest expiring lot when required. By default, AUTOMATICLOT_OUT is set to NO. It is possible to change the value at any time.

With AUTOMATICLOTWARD_TOWARD = YES, the application discharges from a ward (to other wards) the nearest expiring lot automatically when required. By default, AUTOMATICLOTWARD_TOWARD is set to NO. It is possible to change the value at any time. For discharges to patients (drug giving) the lot is never asked.

Note	An application restart is required to apply the modified settings.

3.1.4 LOTWITHCOST

The following table shows the default value and the allowed ones:

Key	Default Value	Valid Values
LOTWITHCOST	yes	yes, no

Open Hospital allows for managing the cost of medicals in the main pharmacy (see 4.2.2.2 Insert stock charging movement in the User’s Guide).

Note	An application restart is required to apply the modified setting.

3.1.5 PATIENTSHEET

The following table shows the default value and the allowed ones:

Key	Default Value	Valid Values
PATIENTSHEET	patient_clinical_sheet	any kind of .jasper file name

Open Hospital can produce a report about the clinical history of a patient (see 8.9 Clinical Sheet in the User’s Guide).

By default, PATIENTSHEET is set to patient_clinical_sheet, that is, the filename of the related report to use for the Clinical Sheet functionality. It is possible to use a different report by installing it in the report folder (see Reports) and by changing this parameter.

Note	An application restart is required to apply the modified setting.

3.1.6 OPDCHART

The following table shows the default value and the allowed ones:

Key	Default Value	Valid Values
OPDCHART	patient_opd_chart	any kind of .jasper file name

Open Hospital can produce a report about the OPD chart of a patient (see 8.9 Clinical Sheet in the User’s Guide).

By default, OPDCHART is set to patient_opd_chart which is the filename of the related report to use for the Clinical Sheet functionality OPD Chart. It is possible to use a different report by installing it in the report folder (see Reports) and by changing this parameter.

Note	An application restart is required to apply the modified setting.

3.1.7 ADMCHART

The following table shows the default value and the allowed ones:

Key	Default Value	Valid Values
ADMCHART	patient_adm_chart	any kind of .jasper file name

Open Hospital can produce a report about the Admission of a patient (see 8.9 Clinical Sheet in the User’s Guide).

By default, ADMCHART is set to patient_adm_chart, that is, the filename of the related report to use for the Clinical Sheet functionality Admission Chart. It is possible to use a different report by installing it in the report folder (see Reports) and by changing this parameter.

Note	An application restart is required to apply the modified setting.

3.1.8 DISCHART

The following table shows the default value and the allowed ones:

Key	Default Value	Valid Values
DISCHART	patient_dis_chart	any kind of .jasper file name

Open Hospital can produce a report about the Discharge of a patient (see 8.9 Clinical Sheet in the User’s Guide).

By default, DISCHART is set to patient_dis_chart which is the filename of the related report to use for the Clinical Sheet functionality Discharge Chart. It is possible to use a different report by installing it in the report folder (see Reports) and by changing this parameter.

Note	An application restart is required to apply the modified setting.

3.1.9 PATIENTBILL

The following table shows the default value and the allowed ones:

Key	Default Value	Valid Values
PATIENTBILL	PatientBill	any kind of .jasper file name

Open Hospital can manage patient bills and produce an A4 format breakdown with his/her items and payments (see 6.2 Functions of Accounting in the User’s Guide).

By default, PATIENTBILL is set to PatientBill, that is, the filename of the related report to use for the bill printing functionality. It is possible to use a different report by installing it in the report folder (see Reports) and by changing this parameter.

Note	An application restart is required to apply the modified setting.

3.1.10 BILLSREPORT

The following table shows the default value and the allowed ones:

Key	Default Value	Valid Values
BILLSREPORT	BillsReport	any kind of .jasper file name

Open Hospital can manage patient bills and produce a report about all bills paid (or not paid) within a span of time (see 8.2 Functions of Accounting in the User’s Guide).

By default, BILLSREPORT is set to BillsReport, that is, the filename of the related report to use for the account printing functionality. It is possible to use a different report by installing it in the report folder (see Reports) and by changing this parameter.

Note	An application restart is required to apply the modified setting.

3.1.11 BILLSREPORTMONTH

The following table shows the default value and the allowed ones:

Key	Default Value	Valid Values
BILLSREPORTMONTH	BillsReportMonth	any kind of .jasper file name

Open Hospital can manage patient bills and produce a report about all bills paid (or not paid) monthly (see 6.2 Functions of Accounting in the User’s Guide).

By default, BILLSREPORTMONTH is set to BillsReportMonth, that is, the filename of the related report to use for the account printing functionality. It is possible to use a different report by installing it in the report folder (see Reports) and by changing this parameter.

Note	An application restart is required to apply the modified setting.

3.1.12 PHARMACEUTICALORDER

The following table shows the default value and the allowed ones:

Key	Default Value	Valid Values
PHARMACEUTICALORDER	PharmaceuticalOrder	any kind of .jasper file name

Open Hospital can produce a report for the Pharmacy Stock critical levels which helps to identify which pharmaceuticals are running low and which ones need to be ordered (see 4.1 Pharmaceuticals in the User’s Guide).

By default, PHARMACEUTICALORDER is set to PharmaceuticalOrder, which is the filename of the related report to use for the pharmacy printing functionality. It is possible to use a different report by installing it in the report folder (see Reports) and by changing this parameter.

Note	An application restart is required to apply the modified setting.

3.1.13 PHARMACEUTICALSTOCK

The following table shows the default value and the allowed ones:

Key	Default Value	Valid Values
PHARMACEUTICALSTOCK	PharmaceuticalStock	any kind of .jasper file name

Open Hospital can produce a report for the Pharmacy Stock Status which identifies which pharmaceuticals are currently available (see 6.1 Pharmaceuticals in the User’s Guide).

By default, PHARMACEUTICALSTOCK is set to PharmaceuticalStock which is the filename of the related report to use for the pharmacy printing functionality. It is possible to use a different report by installing it in the report folder (see Reports) and by changing this parameter.

Note	An application restart is required to apply the modified setting.

3.1.14 PATIENTEXTENDED

The following table shows the default value and the allowed ones:

Key	Default Value	Valid Values
PATIENTEXTENDED	yes	yes, no

Open Hospital allows for the registration of a patient with extended or more detailed information (see 8.4 Insert a new Patient Extended in the User’s Guide).

By default, PATIENTEXTENDED is set to yes. It is possible to set it to no to reduce the amount of data collected and so reduce the workload for the staff involved in data entry.

Note	An application restart is required to apply the modified setting.

3.1.15 OPDEXTENDED

The following table shows the default value and the allowed ones:

Key	Default Value	Valid Values
OPDEXTENDED	yes	yes, no

Open Hospital can link every OPD visit to a registered patient to generate a comprehensive clinical history. For each visit, the user will be asked to select a registered patient or to register a new one, so each visit is attached to the patient’s history (see 5.3 OPD Extended and 10.9 Clinical Sheet in the User’s Guide).

By default, OPDEXTENDED is set to yes. It is possible to set it to no to reduce the amount of data to be collected (only age and sex, no patient registration) and so reduce the workload for the staff involved in data entry.

Note	An application restart is required to apply the modified setting.

3.1.16 MATERNITYRESTARTINJUNE

The following table shows the default value and the allowed ones:

Key	Default Value	Valid Values
MATERNITYRESTARTINJUNE	no	yes, no

Open Hospital allows changing the way the admissions in the Maternity ward are counted within the year; in Open Hospital the first admission of the year for every ward has progressive number 1 (one) and it increments itself automatically up to the end of the year; in some facilities, this is partially true and the progressive numbering starts from June only for the Maternity ward. This option controls which behavior is followed.

By default, MATERNITYRESTARTINJUNE is set to no.

Note	An application restart is required to apply the modified setting.

3.1.17 LABEXTENDED

The following table shows the default value and the allowed ones:

Key	Default Value	Valid Values
LABEXTENDED	yes	yes, no

Open Hospital can force every laboratory exam to be linked to a registered patient, to have a comprehensive clinical history. For each exam, the user will be asked to select a registered patient so from that moment the exam will be attached to the patient’s history (see 5.3.2 New Laboratory Exam in the User’s Guide).

By default, LABEXTENDED is set to yes. Anyway, is possible to set it to no to reduce the amount of data to be collected (only name, age, sex, no patient registration) and so reduce the workload for the staff involved in data entry.

Note	An application restart is required to apply the modified setting.

3.1.18 LABMULTIPLEINSERT

The following table shows the default value and the allowed ones:

Key	Default Value	Valid Values
LABMULTIPLEINSERT	yes	yes, no

Open Hospital can insert multiple laboratory tests per patient at one time to avoid the repetitive operation of selecting a patient or writing his/her name; note that the LABEXTENDED option must also be set to yes (see 5.3.3 Laboratory Multiple Insert in the User’s Guide).

By default, LABMULTIPLEINSERT is set to yes, but if LABEXTENDED is set to no it will be just ignored.

Note	An application restart is required to apply the modified setting.

3.1.19 INTERNALPHARMACIES

The following table shows the default value and the allowed ones:

Key	Default Value	Valid Values
INTERNALPHARMACIES	yes	yes, no

Open Hospital can register all dispensing to patients within a ward. Activating this option, the Pharmaceutical Stock Ward functionality will be available in the application.

By default, INTERNALPHARMACIES is set to yes.

Note	An application restart is required to apply the modified setting.

3.1.20 MERGEFUNCTION

The following table shows the default value and the allowed ones:

Key	Default Value	Valid Values
MERGEFUNCTION	no	yes, no

Open Hospital can merge two patients’ histories into one. This is particularly useful in the case of double registration where different information was collected over time. Activating this option, the Merge functionality will be available in the Admission/Patient module (see Merge function in the User’s Guide).

By default, MERGEFUNCTION is set to no.

Note	An application restart is required to apply the modified setting.

3.1.21 INTERNALVIEWER

The following table shows the default value and the allowed ones:

Key	Default Value	Valid Values
INTERNALVIEWER	yes	yes, any executable filename in the path or with an absolute path

Open Hospital can use a different PDF reader for generated reports. If this parameter is set to yes, the Jasper PDF Viewer is used (see Report Launcher in the User’s Guide). If another PDF viewer is required, specify the executable’s filename; the executable must be available in the desktop environment.

Example in Windows:

INTERNALVIEWER=AcroRd32.exe

INTERNALVIEWER=C:\\Program Files (x86)\\Adobe\\Reader 10.0\\Reader\\AcroRd32.exe

Note	Please note the double file and folder separator “\\”.

Example in Linux:

INTERNALVIEWER=evince

By default, INTERNALVIEWER is set to yes.

Note	An application restart is required to apply the modified setting.

3.1.22 DOC_DIR

The following table shows the allowed value for the DOC_DIR variable:

Key	Default Value	Valid Values
DOC_DIR	doc	any path

Open Hospital documentation is available online; PDF versions of the manuals are packaged with every OH release in a folder that must be accessible by the application; this folder might change depending on the application version, or eventually be customized by the administrator (e.g., subfolder on the Desktop)

Example in Windows:

DOC_DIR=doc
DOC_DIR=C:\\Users\\user\\OneDrive\\Desktop\\doc

Note	Please note the double file and folder separator “\\”.

Example in Linux:

DOC_DIR=doc
DOC_DIR=../doc

By default, DOC_DIR is set to 'doc'.

Note	An application restart is required to apply the modified setting.

Note	The DOC_DIR setting can be automatically generated/overwritten at any Open Hospital startup, by setting the WRITE_CONFIG_FILES option to "on" in the oh.sh / oh.ps1 scripts.

3.1.23 SMSENABLED

The following table shows the default value and the allowed ones:

Key	Default Value	Valid Values
SMSENABLED	no	yes, no

Open Hospital can indicate whether information can be sent to patients via SMS notifications. Enabling or disabling this option only affects the possibility to set, or not set, a therapy as notifiable (see 8.10.7 Notify & SMS in the User’s Guide).

By default, SMSENABLED is set to no.

3.1.23.1 GSM Configuration

To set up a GSM device, the GSM mode has to be defined in the sms.properties file (see sms.properties).

The default settings for a GSM modem should work with the majority of GSM devices (like phones, smartphones, USB modems, etc…). The exception is the PORT parameter which must be changed to match the SERIAL port address used by the device plugged into the system.

If the PORT param is correct but Open Hospital is not able to communicate with the device (try switching to DEBUG log level – or lower - during this setup – see log4j2-spring.properties) and try to use the SetupGSM utility as explained in the next chapter.

3.1.23.2 SetupGSM utility

To setup GSM communication it is possible to use the included SetupGSM utility and follow these instructions:

Plug the device into the system and make sure the system recognizes it, loads a proper driver for it and assigns a serial port (COM)
Launch the OH startup script and select the G option:
- On Windows launch oh.bat → select G option
- On Linux launch oh.sh -G
Once the utility has started, it will scan all plugged devices and will try to recognize the modem (or phone) within them
If the device is recognized as a modem, a confirmation message prompt is shown:

If the identified device is the correct one, just click “yes”, otherwise click “no”, and the scan will continue
Once “yes” is selected the sms.properties file is automatically modified by the utility by inserting the proper port address.

3.1.24 MAINMENUALWAYSONTOP

The following table shows the default value and the allowed ones:

Key	Default Value	Valid Values
MAINMENUALWAYSONTOP	no	yes, no

Open Hospital can keep the main menu always on top so it cannot be overlapped or hidden by other windows.

By default, MAINMENUALWAYSONTOP is set to no.

Note	An application restart is required to apply the modified setting.

3.1.25 RECEIPTPRINTER

The following table shows the default value and the allowed ones:

Key	Default Value	Valid Values
RECEIPTPRINTER	no	yes, no

Open Hospital can manage text or ZPL printers with aim of printing simple receipts in the Accounting module (see 6.2.1.11 Print receipt function in User’s Guide). Once this option is activated, additional parameters are needed in the txtPrinter.properties file to adjust the output with the printer connected to the system (see txtPrinter.properties in this document).

By default, RECEIPTPRINTER is set to no.

Note	The text printer must be set as the default printer.

Note	An application restart is required to apply the modified setting.

3.1.26 VIDEOMODULEENABLED

The following table shows the default value and the allowed ones:

Key	Default Value	Valid Values
VIDEOMODULEENABLED	no	yes, no

Open Hospital can drive any webcam with the aim of capturing patient images in the Admission/Patient module (see 8.4.3 Patient Photo function in User’s Guide). Once this option is activated the related button, New Photo in the New Patient window is available to start and use the webcam.

By default, VIDEOMODULEENABLED is set to no.

Note	An application restart is required to apply the modified setting.

3.1.27 PATIENTVACCINEEXTENDED

The following table shows the default value and the allowed ones:

Key	Default Value	Valid Values
PATIENTVACCINEEXTENDED	yes	yes, no

Open Hospital can register vaccines given to patients (see 7 Vaccines in the User’s Guide). This option allows toggling the patient’s full name in the Patient Vaccine Browser window.

By default, PATIENTVACCINEEXTENDED is set to yes.

Note	An application restart is required to apply the modified setting.

3.1.28 ENHANCEDSEARCH

The following table shows the default value and the allowed ones:

Key	Default Value	Valid Values
ENHANCEDSEARCH	no	yes, no

Open Hospital can optimize memory usage when the number of registered patients becomes large (see 8.2.2 Search patient Enhanced in the User’s Guide). With the enhanced search only, the patient matching a search criterion will be loaded in the memory, otherwise, all patients registered in the system will be loaded in the Patient Browser window.

By default, ENHANCEDSEARCH is set to no. It is possible to toggle this option anytime to reduce the amount of memory needed by the computer or the server.

Note	An application restart is required to apply the modified setting.

3.1.29 XMPPMODULEENABLED

The following table shows the default value and the allowed ones:

Key	Default Value	Valid Values
XMPPMODULEENABLED	no	yes, no

Open Hospital embeds a technology that allows users logged into the application to chat and share information related to the hospital activities (see 11 Communication in the User’s Guide); the SINGLEUSER option must be set to "no". If this option is active, Open Hospital will look for an XMPP Server at startup time.

See the xmpp.properties chapter for instructions on how to setup and configure the XMPP Server communication.

By default, XMPPMODULEENABLED is set to no, but if SINGLEUSER is set to yes XMPPMODULEENABLED is ignored.

Note	An application restart is required to apply the modified setting.

3.1.30 DICOMMODULEENABLED

The following table shows the default value and the allowed ones:

Key	Default Value	Valid Values
DICOMMODULEENABLED	no	yes, no

Open Hospital includes a feature that allows attaching image files to a patient’s clinical sheet. When this option is enabled, an Imaging button is shown in the patient Clinical sheet module.

By default, DICOMMODULEENABLED is set to no.

Note	An application restart is required to apply the modified setting.

3.1.31 DICOMTHUMBNAILS

The following table shows the default value and the allowed ones:

Key	Default Value	Valid Values
DICOMTHUMBNAILS	yes	yes, no

Open Hospital can enable or disable thumbnails in the Imaging Viewer.

By default, DICOMTHUMBNAILS is set to yes.

Note	An application restart is required to apply the modified setting.

3.1.32 DEBUG

The following table shows the default value and the allowed ones:

Key	Default Value	Valid Values
DEBUG	no	yes, no

Open Hospital can run in debug mode which is useful to understand what is happening behind the user graphical interface. Currently, this option affects only the video module, which means that in place of the normal New Patient window (see 8.4.3 Patient Photo function in User’s Guide), the program opens the new special window shown below:

From this window it is possible to have more information about webcams connected to the system. It is possible to apply different resolutions in order to find the best setting or get information about a problem.

Once a photo is produced, Open Hospital remembers the settings and uses them in the future.

By default, DEBUG is set to no.

Note	An application restart is required to apply the modified setting.

3.1.33 ALLOWMULTIPLEOPENEDBILL

The following table shows the default value and the allowed ones:

Key	Default Value	Valid Values
ALLOWMULTIPLEOPENEDBILL	no	yes, no

Open Hospital allows a patient to have multiple open bills (invoices). If this option is enabled, when creating a new bill for a patient if that patient already has an open bill the user is asked to confirm the creation of another one.

By default, ALLOWMULTIPLEOPENEDBILL is set to no.

Note	An application restart is required to apply the modified setting.

3.1.34 OPENEDBILLSREPORT

The following table shows the default value and the allowed ones:

Key	Default Value	Valid Values
OPENEDBILLSREPORT	OH023_BillsReportMonth	OH023_BillsReportMonth

Open Hospital can print the list of open bills. The parameter contains the Jasper report file name to print the list of open bills.

By default, OPENEDBILLSREPORT is set to OH023_BillsReportMonth.

Note	An application restart is required to apply the modified setting.

3.1.35 ALLOWPRINTOPENEDBILL

The following table shows the default value and the allowed ones:

Key	Default Value	Valid Values
ALLOWPRINTOPENEDBILL	no	yes, no

Open Hospital can print the receipt of a single open invoice. When the parameter is enabled, in the Accounting module under the pending tab one can select an open bill and get the receipt by clicking the Receipt button in the buttons panel.

By default, ALLOWPRINTOPENEDBILL is set to no.

Note	An application restart is required to apply the modified setting.

3.1.36 USERSLISTLOGIN

The following table shows the default value and the allowed ones:

Key	Default Value	Allowed Values
USERSLISTLOGIN	no	yes, no

When Open Hospital is used in multi-user mode, i.e. SINGLEUSER = no, it is possible to choose between two different login modes:

(1) by typing the username directly in a textbox, if USERSLISTLOGIN is set to NO (default):

(2) by selecting the username from a list of users, if USERSLISTLOGIN is set to YES:

By default, USERSLISTLOGIN is set to no.

Note	An application restart is required to apply the modified setting.

3.1.37 STRONGPASSWORD

The following table shows the default value and the allowed ones:

Key	Default Value	Allowed Values
STRONGPASSWORD	yes	yes, no

By default, the value of STRONGPASSWORD is set to yes indicating that the password must contain at least one alphabetic, numeric, and special character. The list of recognized special characters is: _$&+,:;=\?@#|/'<>.^()%!-*

Note	An application restart is required to apply the modified setting.

3.1.38 STRONGLENGTH

The following table shows the default value and the allowed ones:

Key	Default Value	Allowed Values
STRONGLENGTH	6	0 or a positive integer value

The value of STRONGLENGTH is the minimum length of a user’s password. To disable the checking of the password’s length set STRONGLENGTH to 0.

Note	If STRONGPASSWORD is set to yes, then STRONGLENGTH should be set to a value greater than or equal to 3 as that is the minimum number of unique characters required.

Note	An application restart is required to apply the modified setting.

3.1.39 PASSWORDTRIES

The following table shows the default value and the allowed ones:

Key	Default Value	Allowed Values
PASSWORDTRIES	5	0 or a positive integer value greater than or equal to 5

The value of PASSWORDTRIES is the maximum number of consecutive failed passwords when attempting to log in before the account is locked. To disable the checking of the consecutive failed attempts set PASSWORDTRIES to 0.

Note	An application restart is required to apply the modified setting.

3.1.40 PASSWORDLOCKTIME

The following table shows the default value and the allowed ones:

Key	Default Value	Allowed Values
PASSWORDLOCKTIME	60	a positive integer value greater than or equal to 60; the unit of time is minutes

The value of PASSWORDLOCKTIME is the number of minutes that an account is locked after failing to specify the correct password for the number of times specified by the PASSWORDTRIES variable described above.

Note	An application restart is required to apply the modified setting.

3.1.40 PASSWORDIDLE

The following table shows the default value and the allowed ones:

Key	Default Value	Allowed Values
PASSWORDIDLE	365	a positive integer value greater than or equal to 0; the unit of time is days

The value of PASSWORDIDLE specifies the maximum number of days that an account can be unused before being locked and requiring intervention by the administrator. To disable this check set PASSWORDIDLE to 0.

Note	An application restart is required to apply the modified setting.

3.1.41 PATIENTPHOTOSTORAGE

The following table shows the default value and the allowed ones:

Key	Default Value	Valid Values
PATIENTPHOTOSTORAGE	DB	DB, <path_to_folder>

Open Hospital can save the patient’s profile picture in the database or on the file system.

Note	The maximum size for a patient’s profile picture is limited to 32,768 bytes. If a bigger image is provided, it will automatically be resized.

If the PATIENTPHOTOSTORAGE parameter is set to a path (that is, not "DB"), then Open Hospital looks for or saves the patient’s profile picture in the specified path.

If the PATIENTPHOTOSTORAGE parameter is set to "DB", then Open Hospital looks for or saves the patient’s profile picture in the Open Hospital database.

By default, PATIENTPHOTOSTORAGE is set to "DB".

Note	An application restart is required to apply the modified setting.

3.1.42 SESSIONTIMEOUT

The following table shows the default value and the allowed ones:

Key	Default Value	Allowed Values
SESSIONTIMEOUT	5	positive integer value

The value SESSIONTIMEOUT represents the time in minutes of user inactivity beyond which the software application performs the automatic logout.

Note	An application restart is required to apply the modified setting.

3.1.43 EXAMINATIONCHART

The following table shows the default value and the allowed ones:

Key	Default Value	Allowed Values
EXAMINATIONCHART	patient_examination	any kind of .jasper file name

Open Hospital can produce a report about patient_examinations. (see 8.5.2 Patient Examination in the User’s Guide).

By default, EXAMINATIONCHART is set to patient_examination which is the filename of the related report to use for the Patient Examination functionality. It is possible to use a different report by installing it in the report folder (see Reports) and by changing this parameter.

Note	An application restart is required to apply the modified setting.

3.1.44 VISITSHEET

The following table shows the default value and the allowed ones:

Key	Default Value	Allowed Values
VISITSHEET	WardVisits	any kind of .jasper file name

By default, VISITSHEET is set to WardVisits which is the filename of the related report to use for the Visit Sheet functionality. It is possible to use a different report by installing it in the report folder (see Reports) and by changing this parameter.

Note	An application restart is required to apply the modified setting.

3.1.45 TELEMETRYENABLED

The following table shows the default value and the allowed ones:

Key	Default Value	Allowed Values
TELEMETRYENABLED	yes	yes, no

By default, the value of TELEMETRYENABLED is the set to yes indicating that the Telemetry module is enabled.

When the Telemetry module is enabled, users are presented with the option to participate in anonymous data collection on the software’s usage during the initial application launch. This process is designed to gather information that contributes to the ongoing improvement of software quality. User-selected data collection preferences, customizable at any time, will be applied automatically during subsequent launches.

The collected data is transmitted to a server managed by ISF, solely for the purpose of optimizing the application and generating usage statistics. ISF ensures that this data is treated anonymously and with utmost respect for user privacy.

The Telemetry module can be disabled at any time through the Settings menu or via settings.properties.

3.1.46 PARAMSURL

This is the URL of the online configuration/parameters file.

Note	This setting is not meant to be modified by the user.

3.2 database.properties

Database configuration is set in the database.properties file. Default database configuration is available in the database.properties.dist file:

jdbc.url=jdbc:mysql://DBSERVER:DBPORT/DBNAME
jdbc.username=DBUSER
jdbc.password=DBPASS

Use the provided startup scripts in order to automatically generate the database.properties file from the corresponding .dist file; after generation, optionally adjust the following parameters:

DBSERVER: the IP address of the OH database server. IP address can be set to:
127.0.0.1 – localhost / loopback network interface (local computer)
192.168.0.100 – an example of a private IP address (LAN)
217.147.110.117 – an example of a public IP address (WAN)
DBPORT: the TCP port of the OH database server - default is "3306"
DBNAME: the database name - default is "oh"
DBUSER: the database user - default is "isf"
DBPASS: the database user password

Note	An application restart is required to apply the modified setting.

Note	The same settings must be applied in log4.properties, see log4j2-spring.properties in this manual.

Note	The database.properties file can be automatically generated/overwritten at any Open Hospital startup, by setting the WRITE_CONFIG_FILES option to "on" in the oh.sh / oh.ps1 scripts.

3.3 dicom.properties

Imaging configuration is set in the dicom.properties file. A default imaging configuration is available in the dicom.properties.dist file:

#dicom.manager.impl=org.isf.dicom.manager.FileSystemDicomManager        # filesystem storage
#dicom.manager.impl=org.isf.dicom.manager.SqlDicomManager               # database storage
#dicom.max.size=1024B, 2048B, 1M, 16M, 256M, 512M, 1024M, 1G            # image size examples
dicom.manager.impl=org.isf.dicom.manager.DICOM_STORAGE
dicom.storage.filesystem=OH_PATH_SUBSTITUTE/DICOM_DIR
dicom.max.size=DICOM_SIZE

Use the provided startup scripts in order to automatically generate the dicom.properties file from the corresponding .dist file; after generation, optionally adjust the following parameters:

DICOM_STORAGE: This property accepts one of the following:
- SqlDicomManager: Image files are stored in the database
- FileSystemDicomManager: Image files are stored in the file system
OH_PATH_SUBSTITUTE/DICOM_DIR: if the value of the first parameter is set to "FileSystemDicomManager", this property specifies the path where the image files are stored. It is possible to specify a local folder (data/dicom_storage is the default path under the OH installation folder) or to set a shared network folder, useful for LAN - client/server environment. The suggested configuration is to map the network/NFS folder under the data/dicom_storage path with a symbolic link. The shared folder needs read/write permissions for uploading images. Always use slash "/" in the path variable and not backslash "\".
DICOM_SIZE: maximum allowed size for a dicom/jpg image (the MariaDB/MySQL server setting max_allowed_packet should be set with the same or a larger value). If not specified the default value of "4M" is used.

Example dicom.properties file:

dicom.manager.impl=org.isf.dicom.manager.FileSystemDicomManager
dicom.storage.filesystem=Z:/OH/Shared/Dicom_images
dicom.max.size=4M

Note	The dicom.properties file can be automatically generated/overwritten at any oh.sh / oh.ps1 startup, by setting the WRITE_CONFIG_FILES option to "on" in the oh.sh / oh.ps1 scripts.

3.4 examination.properties

The examination module configuration is set in the examination.properties file. A default configuration file for this module is available in the examination.properties.dist file:

# This file contains PatientExamination module settings
LIST_SIZE = 10
HEIGHT_MIN = 0
HEIGHT_MAX = 250
HEIGHT_INIT = 0
#HEIGHT_STEP = 1
#WEIGHT_UNIT = kg
WEIGHT_MIN = 0
WEIGHT_MAX = 200
WEIGHT_INIT = 0
WEIGHT_STEP = 0.1
#AP_UNIT = mmHg
AP_MIN_INIT = 80
AP_MAX_INIT = 120
#HR_UNIT = bpm
HR_MIN = 0
HR_MAX = 240
HR_INIT = 60
#TEMP_UNIT = *C
TEMP_INIT = 36
TEMP_MIN = 30
TEMP_MAX = 50
TEMP_STEP = 0.1
#SAT_UNIT = %
SAT_INIT = 98
SAT_MIN = 50
#SAT_MAX = 100
SAT_STEP = 0.1
HGT_MIN = 30
HGT_MAX = 600
HGT_INIT = 80
DIURESIS_MIN = 0
DIURESIS_MAX = 2500
DIURESIS_INIT = 100
RR_INIT = 20
RR_MIN = 0
RR_MAX = 100

LIST_SIZE: the maximum number of examinations that can be viewed in the history. Must be less than or equal to 10
HEIGHT_MIN: the height minimum value (in cm), used to initialize the height slider in the Patient Examination window
HEIGHT_MAX: the height maximum value (in cm), used to initialize the height slider in the Patient Examination window
HEIGHT_INIT: the height default value (in cm)
WEIGHT MIN: the weight minimum value (in Kg), used to initialize the Weight slider in the _Patient Examination window
WEIGHT MAX: the weight maximum value (in Kg), used to initialize the Weight slider in the _Patient Examination window
WEIGHT _INIT: the weight default value (in Kg)
WEIGHT _STEP: the step (in Kg) used when moving the weight slider
AP _MIN: the Arterial pressure minimum value (in mmHg)
AP _MAX: the Arterial pressure maximum value (in mmHg)
HR _MIN: the Heart rate minimum value (in bmp)
HR _MAX: the Heart rate maximum value (in bmp)
HR _INIT: the Heart rate default value (in bmp)
TEMP _INIT: the temperature default value (in °C)
TEMP _MIN: the temperature minimum value (in °C)
TEMP _MAX: the temperature maximum value (in °C)
TEMP _STEP: the temperature step (in °C) used when moving the slider
SAT _INIT: the saturation default value (%)
SAT _MIN: the saturation minimum value (%)
SAT _STEP: the saturation step (%) used when moving the slider
HGT_INIT: = the Hemo Glucose Test default value (in mg/dl)
DIURESIS_INIT: = the Daily Urine Volume default value (in ml)

3.5 log4j2-spring.properties

The logging configuration is set in the log4j2-spring.properties file. Default logging configuration is available in the log4j2-spring.properties.dist file:

status = INFO
rootLogger.level = INFO
rootLogger.appenderRef.console.ref = STDOUT
rootLogger.appenderRef.rolling.ref = RollingFile

# Direct log messages to STDOUT
appender.console.type = Console
appender.console.name = STDOUT
appender.console.layout.type = PatternLayout
appender.console.layout.pattern = [%d{dd/MMM/yyyy HH:mm:ss}] [%X{OHUserGroup}:%X{OHUser}] %-p - %m%n

# File Appender (with classes), daily rotation
appender.rolling.type = RollingFile
appender.rolling.name = RollingFile
appender.rolling.fileName= LOG_DEST/openhospital.log
appender.rolling.filePattern= LOG_DEST/openhospital.log.%d{yyyy-MM-dd}
appender.rolling.layout.type = PatternLayout
appender.rolling.layout.pattern = [%d{dd/MMM/yyyy HH:mm:ss}] [%X{OHUserGroup}:%X{OHUser}] %-p - %m (%l)%n
appender.rolling.policies.type = Policies
# To change log file every day
appender.rolling.policies.time.type = TimeBasedTriggeringPolicy
appender.rolling.policies.time.interval = 1
appender.rolling.policies.time.modulate = true


# DB Appender (table columns)
appender.jdbc.type = JDBC
appender.jdbc.name = jdbc
appender.jdbc.connectionSource.driverClassName = com.mysql.cj.jdbc.Driver
appender.jdbc.connectionSource.type = DriverManager
appender.jdbc.connectionSource.connectionString = dbc:mysql://DBSERVER:DBPORT/DBNAME?autoReconnect=true
appender.jdbc.connectionSource.userName = DBUSER
appender.jdbc.connectionSource.password = DBPASS
appender.jdbc.tableName = logs
appender.jdbc.ignoreExceptions = false
appender.jdbc.columnConfigs[0].type = COLUMN
appender.jdbc.columnConfigs[0].name = LOG_TIME
appender.jdbc.columnConfigs[0].pattern = %d
appender.jdbc.columnConfigs[0].isUnicode = false
appender.jdbc.columnConfigs[1].type = COLUMN
appender.jdbc.columnConfigs[1].name = LOG_LEVEL
appender.jdbc.columnConfigs[1].pattern = %5p
appender.jdbc.columnConfigs[1].isUnicode = false
appender.jdbc.columnConfigs[2].type = COLUMN
appender.jdbc.columnConfigs[2].name = MESSAGE
appender.jdbc.columnConfigs[2].pattern = %mm%ex%n
appender.jdbc.columnConfigs[2].isUnicode = false


# Assigning appenders to Hibernate packages (DB loggers)
# - hibernate.SQL to DEBUG for SQL queries to be logged
# - hibernate.type to TRACE for queries parameters to be logged with "binding parameter [?]"
##logger.hibernate-SQL.name=org.hibernate.SQL
##logger.hibernate-SQL.level=DEBUG
##
##logger.hibernate-type.name=org.hibernate.type
##logger.hibernate-type.level=TRACE

Use the provided OH startup scripts in order to automatically generate the log4j2-spring.properties file from the corresponding .dist file; after generation, optionally adjust the following parameters:

DBSERVER: the IP address of the OH database server. IP address can be set to:
127.0.0.1 – localhost / loopback network
192.168.0.100 – an example of a private IP address (LAN)
217.147.110.117 – an example of a public IP address (WAN)
DBPORT: the TCP port of the OH database server - default is "3306"
DBNAME: the database name - default is "oh"
DBUSER: the database user - default is "isf"
DBPASS: the database user password
LOG_LEVEL: the OH application log level - can be set to INFO|DEBUG|TRACE

Note	The same settings must be applied in the database.properties configuration file, see database.properties in this manual.

status = INFO
rootLogger.level = INFO
rootLogger.appenderRef.rolling.ref = RollingFile

To investigate bugs or issues, the log level can be increased to "TRACE" in order to log more detailed information:

status = TRACE
rootLogger.level = TRACE
rootLogger.appenderRef.rolling.ref = RollingFile

Logging can be routed to the database (DB) by adding the respective appender:

status = INFO
rootLogger.level = INFO
rootLogger.appenderRef.console.ref = STDOUT
rootLogger.appenderRef.rolling.ref = RollingFile
rootLogger.appenderRef.db = JDBC

Logging can also be routed to standard output (the console window) with:

status = INFO
rootLogger.level = INFO
rootLogger.appenderRef.console.ref = STDOUT
rootLogger.appenderRef.rolling.ref = RollingFile

If the DB appender is specified, the configuration must be set to match the settings in the database.properties file (see database.properties).

Note	The log4j2-spring.properties file can be automatically generated/overwritten at any Open Hospital startup, by setting the WRITE_CONFIG_FILES option to "on" in the oh.sh / oh.ps1 scripts.

Note	DEBUG mode can generate large log files and should be avoided in a production environment.

Note	An application restart is required to apply the modified setting.

3.6 sms.properties

The SMS communication module configuration is set in the sms.properties file. A default configuration file for this module is available in the sms.properties.dist file:

##################################################################
# Global configuration
##################################################################
# use: gsm-gateway-service || skebby-gateway-service || textbelt-gateway-service
sms.gateway=textbelt-gateway-service
sms.gateway.thread.timeout=3000
sms.gateway.thread.loop=15
sms.gateway.thread.icc=+39

... other sections

sms.gateway: the SMS sender mode. Can take three values:
- gsm-gateway-service: requires a GSM modem connected to a COM port. The administrator should configure the SMSGateway/GSM.properties file to set the suitable PORT.
- skebby-gateway-service: requires a Skebby provider account.
- textbelt-gateway-service: requires a Textbelt provider account.
TIMEOUT: the timeout for the HTTP request. Required when sms.gateway is set to skebby-gateway-service or textbelt-gateway-service.
LOOP: the delay used by the sender to fetch new SMS operations. The value is in seconds.
ICC: the International Country Code that needs to be added to the phone numbers (if missing).

3.6.1 skebby-gateway-service

The default skebby-gateway-service section is:

##################################################################
# Skebby configuration
##################################################################
skebby-gateway-service.username=
skebby-gateway-service.password=
skebby-gateway-service.ribbon.base-url=https://api.skebby.it:443
# USER_KEY and ACCESS_TOKEN avoids the login call every time we need to send sms
skebby-gateway-service.accessToken=
skebby-gateway-service.userKey=

This file defines the parameters for sending SMS using the Skebby HTTP API.

username: the username for authenticating to the Skebby server.
password: the password for authenticating to the Skebby server.
ribbon.base-url: the URL of the Skebby HTTP API.
accessToken: the token generated by the Skebby provider upon user request (it replaces username)
userKey: the key generated by the Skebby provider upon user request (it replaces password)

3.6.2 textbelt-gateway-service

The default textbelt-gateway-service section is:

##################################################################
# Textbelt configuration
##################################################################
# enables/disables server testing mode (so that textbelt will do fake actions)
textbelt-gateway-service.enable-testing-mode=false
# use: textbelt (in order to send 1 free sms per day) or your api key (if you purchased sms)
textbelt-gateway-service.key=textbelt
textbelt-gateway-service.ribbon.base-url=https://textbelt.com:443

This file defines the parameters for sending SMS using the Skebby HTTP API.

enable-testing-mode: if set to "true", textbelt will do fake actions upon user/application requests.
key: the API key (if using a purchased sms) from Textbelt provider (one can use "textbelt" to send 1 free sms per day)
ribbon.base-url: The URL of the Textbelt HTTP API.

3.7 telemetry.properties

The telemetry configuration is set in the telemetry.properties file. A default configuration file for this module is available in the telemetry.properties.dist file:

# number of seconds to check if it should send a message
telemetry.daemon.thread.loop.seconds=14400

# enabled remote geo ip lookup service
# allowed values:
# - geoiplookup-remote-service
# - ipapi-remote-service
telemetry.enabled.geo.ip.lookup.service=geoiplookup-remote-service
# endpoints remote services
geoiplookup-remote-service.ribbon.base-url=https://json.geoiplookup.io
ipapi-remote-service.ribbon.base-url=http://ip-api.com/json

This file is used only if the TELEMETRYENABLED flag is true (see TELEMETRYENABLED in this document).

The file has the following configurable parameters:

telemetry.daemon.thread.loop.seconds: number of seconds the Telemetry module should try again to send the telemetry data; if the telemetry data have been sent in the same day it will not send again.
telemetry.enabled.geo.ip.lookup.service: the GeoIP service to use among the ones available in the comment: geoiplookup-remote-service or ipapi-remote-service; more services may be added in the future.
<service>.ribbon.base-url: the URL for each available GeoIP service

Note	An application restart is required to apply the modified setting.

3.8 txtPrinter.properties

The text printer configuration is set in the txtPrinter.properties file. A default configuration file for this module is available in the txtPrinter.properties.dist file:

# This file contains text printing information
# MODE = TXT, PDF or ZPL
USE_DEFAULT_PRINTER=yes
PRINT_AS_PAID=no
PRINT_WITHOUT_ASK=no
MODE=PDF
#TXT_CHAR_HEIGHT=10
#TXT_CHAR_WIDTH=10
ZPL_FONT_TYPE=0
ZPL_ROW_HEIGHT=25

This file is used only if the RECEIPTPRINTER flag is enabled (see RECEIPTPRINTER in this document).

The file has the following configurable parameters:

USE_DEFAULT_PRINTER: If it is set to yes, Open Hospital will use the default printer, otherwise it will show the system printing dialog allowing a change to the printer at every print attempt:

PRINT_AS_PAID: This changes the behavior when a Bill is set to PAID in the Accounting module (see 6.2.1.11 Print receipt function in User’s Guide).
- If it is set to yes, Open Hospital will try to print a receipt just after a Bill is set to PAID
  - A confirmation window will appear (see below), otherwise, it must be done after, by pressing the Edit Bill button on the already closed (“C”) bill

PRINT_WITHOUT_ASK: if set to yes Open Hospital will try to print the receipt without the confirmation window
MODE: the MODE can take three values:
- TXT: the bill is printed as pure text (no graphics)
- PDF: the bill will be printed as a PDF
- ZPL: the text printer connected to the system works with ZPL language (an EPL evolution for Zebra Label Printer)
ZPL_FONT_TYPE: a 0 (zero) value stands for a standard character; the value can be changed to “A”, “B”, “C”, etc. according to the device datasheet, to obtain a better look
ZPL_FONT_SIZE: an integer value to adjust the character size to obtain a better look

The best way to set these parameters for the device is to set them one by one and check the different results until the best fit is reached.

Note	An application restart is required to apply the modified setting.

3.9 xmpp.properties

The XMPP module configuration is set in the xmpp.properties file. A default configuration file for this module is available in the xmpp.properties.dist file:

# This file contains Xmpp Server information
DOMAIN=127.0.0.1
PORT=5222

This file is used only if the XMPPMODULEENABLED flag is enabled (see XMPPMODULEENABLED in this document).

To use the Communication module (see 11 Communication in the User’s Guide), an XMPP Server must be installed and configured separately on a server/computer in the local network. The XMPP server can also be installed on the same machine as the OH database server.

The most common XMPP Server is the free and open-source project Ignite Openfire® (https://www.igniterealtime.org/projects/openfire/) available for Linux, Windows, and Mac.

Once the XMPP Server is installed, active and running set the two parameters in the xmpp.properties file as follows:

DOMAIN – the IP address of the XMPP server (it could be the same as the database server)
PORT – 5222 or another if set differently

Note	An application restart is required to apply the modified setting.

3.9.1 OpenFire Settings

The XMPP module needs some knowledge about the XMPP protocol and how an XMPP server works.

Every new user login into Open Hospital creates an OpenFire user with the same username and password (even if passwords are saved differently in OH and OpenFire DB). For this reason, the OH "admin" user may conflict with the OpenFire user, not allowing the log in as admin and to chat.

Note	If the admin user needs to chat with other users consider creating another "superuser" in OH under the "admin" group.

To allow users to see each other and communicate via XMPP protocol, they must belong to the same OpenFire "group" and have the other users in their own "roster" (find more comprehensive information about "group" and "roster" in the online documentation).

Please follow these settings:

Install the OpenFire server (it is better if from the zip file) on a writable path
Set in both OpenFire and in the xmpp.properties file an IP address rather than the FQDN (e.g., 127.0.0.1)
Set OpenFire to use Embedded DB
Create a group "OH" in the OpenFire server and enable the "Contact List (Roster) Sharing"
Add new users automatically created from OH to the "OH" group
Consideration should be given to using the OpenFire plugin to automatically add new users to a group (e.g., registration plugin https://www.igniterealtime.org/projects/openfire/plugins/registration.jar)

3.10 default_credentials.properties

Open Hospital is packaged with a login "hint" visible only if the default_credentials.properties file is found.

Note	Mouse over the "i" icon to see the hint.

To not show the hint just delete default_credentials.properties file.

The original values are found in default_credentials.properties.dist and default_demo_credentials.properties.dist files.

# Default credentials
admin:admin
guest:guest

# Default demo credentials
admin:admin
guest:guest
laboratorist:laboratorist
doctor:doctor

Note	It is always recommended to change the admin user password in a production environment.

3.11 Bundles

Bundles are the language (or translation) files provided with Open Hospital. As described in the LANGUAGE chapter, Open Hospital comes with different available languages in the folder bundles/ within the package file:

language_XY.properties

where XY is an international country code.

These property files (text format) contain multiple key = value pairs containing localized text for the language specified.

All files must be encoded in UTF-8 to accept any language-specific characters (e.g. è ì ò à ñ ú ù ¡ ¿ …).

3.11.1 New Translations

To create a new translation, simply copy the English file, rename it with the new country code in place of the “XY” in the filename, and start translating with a simple text editor. A text editor can also be used to modify existing translations that are incorrect.

For instance, if to create an Arabic translation, copy a new bundle from the English one by copying language_en.properties to a new file language_ar.properties.

Then edit the Arabic bundle file and set the LANGUAGE parameter to ar to start testing the translation.

4 Reports

Reports in Open Hospital are produced with JasperReports® technology that allows one to design a report in a WYSIWYG (What You See Is What You Get) way, connect it to a datasource (DB), test it, modify it, and then compile it to use it in the application software.

Open Hospital reports are divided into three different folders, i.e. rpt_base/, rpt_stat/ and rpt_extra/ folder (see Folders in this document):

rpt_base/ folder contains all the hardcoded reports used by the application
rpt_stat/ folder contains the OHxxx basic reports available in the Statistics menu
rpt_extra/ folder contains additional reports defined by the user also available in the Statistics menu. Users can create new custom reports, copy them to the folder and the application will make them available in the Statistics menu.

Each report consists of two files:

a .jrxml file: JasperReport XML file, that can be modified with a proper editor
a .jasper file: Jasper file, which is the compiled version that can be run in Open Hospital; this file is produced on the jrxml base
some reports could also have more than one .properties file that works for the localization, which means that the report has been translated to appear in more languages (the default is English). At least the default .properties file should contain the jTitle property that defines the name visualized in the Open Hospital application, otherwise the application will not show the report (this can be useful for subreports).

The editor to create and modify JasperReports® is TIBCO Jaspersoft® Studio version 6.14.0 or later, a free and open-source software.

With Jaspersoft® Studio it is possible to edit Open Hospital reports and re-compile them in the same location to be found and used by the Open Hospital application.

5 Installing Open Hospital 1.14.2 in Eclipse EE

The OH source code is available on GitHub at the following links:

openhospital-core
openhospital-gui
openhospital-doc

Please use EGit (Eclipse Plugin for Git) to clone the code into the Eclipse instance.

Assuming Eclipse EE, MariaDB/MySQL and the Java Virtual Machine 11 or higher (Java8 or greater) are already installed on the computer, this chapter will focus on cloning version 1.14.2 into the Eclipse J2EE (or Eclipse EE) environment.

Please follow these EGit User Guide - Working with remote Repositories.

5.1 Run the Project

Note	Before running the project, the database must be created as explained in the chapter MySQL Server and Open Hospital Database.

To run the application, look for class openhospital-gui/src/main/java/org/isf/menu/gui/Menu.java, then right-click on it and choose Run As → Java Application. If everything is OK, the splash screen will appear. If not, look in the Eclipse console for any error or warning messages.

Open Hospital’s advanced features require “native” libraries generated to match the computer’s operating system. Right-click on the project’s name, then select Run As → Run Configurations:

A “Run Configurations” window opens. Choose Java Application → <application’s name> - Menu (1) on this example. Select the “Main” tab, write “angal” on the “Project” field and check if the “Main class” is org.isf.menu.gui.Menu.

Select the “Arguments” tab and fill in the “VM arguments” path typing (on a single line):

-Dsun.java2d.dpiaware=false -Djava.library.path=lib\native\<OS name>

<OS name> can be “Mac_OS_X”, “Solaris”, “Linux”, “Win64” (for 64bit Windows) or “Windows” (for 32bit Windows) according to the folder’s schema found in the related folder “native”. Click on “Run” to close the window and run the application.

Now that the run configuration settings have been selected, OH can be launched by just clicking on the “Run” button (shown below by an arrow).

Because of the default settings, Open Hospital’s first run does not show the login window. The system defaults to “single-user” mode by default. This can be verified by the “SINGLEUSER=yes” string on the third row of the settings.properties file. In production use this is unacceptable as Open Hospital must be accessible only to the administrator and logged users. Click on the triangle near the project’s name, do the same on the “rsc” subfolder and then double-click on the settings.properties file.

Replace “yes” with “no” on the “SINGLEUSER” row. Press CTRL+S (or Command+S on Mac) to save the change. Now rerun the application and after the splash window, a “login” window opens. Click on the drop-down menu to choose the role. To access as the administrator, select “admin” and type the password. The default is “admin”. The administrator has the right to register users as guests. Guests have to choose “guest” from the drop-down menu and then type their password.

If the password is not correct, an error message is shown, asking the user to try again.

To better understand the processes built in the software, also enable the “Standard Output” in log4j2-spring.properties as explained in the chapter log4j2-spring.properties.

6 Update Open Hospital

New releases, as well as this Admin Manual and the User Manual, are regularly released on GitHub/SourceForge. See the Download section for more details. NOTE: Following instructions only apply between “official releases”.

Minor releases (if not otherwise specified) do not need changes to the database structure, so the working copy can be replaced on each client with the new one and then connect to the same DB (see database.properties and log4j2-spring.properties).

It is important to keep/preserve files that have been created or modified, especially configuration/settings and data files (see Configuration). The easiest way is to backup the working copy and re-apply those settings in the new installation (see the Backup & Restore chapter).

Major Releases: Changes are documented in the RELEASE_NOTES file.

6.1 Update Database

Major OH releases usually require changes to the database structure, and these changes are implemented via different SQL scripts included in the sql/update folder (e.g.):

Previous OH version	New OH version	Database update script
1.8.4	1.9	update_1_8_4-1_9.sql
1.9	1.10	update_1_9-1_10.sql
1.10	1.10	update_1_10-1_11.sql
1.11	1.12	update_1_11-1_12.sql
1.12	1.13	update_1_12-1_13.sql
1.13	1.14	update_1_13-1_14.sql

To perform the database update process follow these steps:

Close the program if it is still running
Backup the current database for safety (see Backup & Restore)
Open a terminal in the folder sql/update (e.g.):

C:\WINDOWS\system32> cd C:\Users\OH\OpenHospital-v1.14.2\sql\update

C:\Users\OH\OpenHospital-v1.14.2\sql\update>

Run the following commands (e.g.):

C:\Users\OH\OpenHospital.1.14.2\sql\update> mysql –u root -p [-h hostname/ip address]

Enter password: ****

Use the ‘root’ password chosen during the installation process. The terminal should reply with the MySQL client command line prompt:

MariaDB>

Select the open hospital database;

MariaDB>USE oh;

Execute all the SQL scripts from your current OH version up to the new one:

Example: updating version from 1.10.X to 1.13.X

MariaDB> source update_1_10-1_11.sql

MariaDB> source update_1_11-1_12.sql

MariaDB> source update_1_12-1_13.sql

...

If any error message occurs you can report an issue here: https://openhospital.atlassian.net/

6.2 Update Client

If the database upgrade procedure is successful, it is possible to update the OH software by replacing the OH working copy on each client with the new one. (see database.properties and log4j2-spring.properties). Remember to maintain the configuration files that have been changed, to preserve the custom settings. (see Configuration). The most common way is to backup the working copy and re-apply those settings in the new one (see Backup & Restore). Start the program and check the log files (data/logs) to ensure that the new version is running and has no error messages.

6.3 Update Portable

Note	Open Hospital, used in PORTABLE mode, is not meant to be used in a production environment. To migrate a portable installation to a full client/server configuration, keeping the existing data, the following steps must be performed:

Close Open Hospital;
use oh.sh / oh.ps1 e option to export the database
overwrite local working copy with the new version files
use oh.sh / oh.ps1 r option to restore exported database

If needed, start the PORTABLE instance in SERVER mode, connect to the local running database and apply the required SQL scripts.

7 Support

For support, or questions about updating, migrating, or maintaining an Open Hospital installation, please check our website at https://www.open-hospital.org. You can contact us at: https://www.open-hospital.org/contact and specify:

A brief history of the organization;
The country where the installation is and the language used;
Technical details of the OH installation;
The application logs (see Help chapter in the User’s Guide)
The current Open Hospital version;
Complete the Open Hospital Assessment online-form form

8 License

Informatici Senza Frontiere Onlus, 2022
Administrator’s Guide, © 2023 by Informatici Senza Frontiere Onlus
Policies is made available under a Creative Commons Attribution-ShareAlike 4.0 International License: https://creativecommons.org/licenses/by-sa/4.0//.

1. Informatici Senza Frontiere - https://www.informaticisenzafrontiere.org

2. DataBase Management System

3. See https://www.mariadb.org

4. https://mariadb.org/download/

5. https://mariadb.org/documentation/

Files

AdminManual.adoc

Latest commit

History

AdminManual.adoc

File metadata and controls

Open Hospital 1.14.2 - Administrator’s Guide

Open Hospital

1 Introduction

1.1 Main Features

1.2 Hardware requirements

1.3 Software requirements

1.5 Download

1.6 Unpack

1.7 Documentation

2 Installation

2.1 OH - CLIENT mode

2.1.1 Prerequisites - Software compatibility matrix

2.1.2 Java Runtime Environment (JRE)

2.1.3 Database Server

2.1.3.1 MariaDB/MySQL - Server installation

2.1.3.2 MariaDB/MySQL - Configuration

2.1.3.3 MariaDB/MySQL - Networking

2.1.4 OH - Database creation

2.1.5 OH - CLIENT configuration

2.1.6 OH - Startup and run

2.2 OH - PORTABLE mode

2.3 OH - SERVER mode (portable)

2.4 Backup & Restore

2.4.1 Backup of database (alternative with MySQL Workbench®)

2.4.2 Restore of database (alternative with MySQL Workbench®)

2.4.3 Backup of OH code and settings

2.5 Folders and directory structure

2.6 Appearance

3 Configuration

3.1 settings.properties

3.1.1 LANGUAGE

3.1.2 SINGLEUSER

3.1.3 AUTOMATICLOT

3.1.4 LOTWITHCOST

3.1.5 PATIENTSHEET

3.1.6 OPDCHART

3.1.7 ADMCHART

3.1.8 DISCHART

3.1.9 PATIENTBILL

3.1.10 BILLSREPORT

3.1.11 BILLSREPORTMONTH

3.1.12 PHARMACEUTICALORDER

3.1.13 PHARMACEUTICALSTOCK

3.1.14 PATIENTEXTENDED

3.1.15 OPDEXTENDED

3.1.16 MATERNITYRESTARTINJUNE

3.1.17 LABEXTENDED

3.1.18 LABMULTIPLEINSERT

3.1.19 INTERNALPHARMACIES

3.1.20 MERGEFUNCTION

3.1.21 INTERNALVIEWER

3.1.22 DOC_DIR

3.1.23 SMSENABLED

3.1.23.1 GSM Configuration

3.1.23.2 SetupGSM utility

3.1.24 MAINMENUALWAYSONTOP

3.1.25 RECEIPTPRINTER

3.1.26 VIDEOMODULEENABLED

3.1.27 PATIENTVACCINEEXTENDED

3.1.28 ENHANCEDSEARCH

3.1.29 XMPPMODULEENABLED

3.1.30 DICOMMODULEENABLED

3.1.31 DICOMTHUMBNAILS

3.1.32 DEBUG

3.1.33 ALLOWMULTIPLEOPENEDBILL

3.1.34 OPENEDBILLSREPORT

3.1.35 ALLOWPRINTOPENEDBILL

3.1.36 USERSLISTLOGIN

3.1.37 STRONGPASSWORD

3.1.38 STRONGLENGTH

3.1.39 PASSWORDTRIES

3.1.40 PASSWORDLOCKTIME

3.1.40 PASSWORDIDLE

3.1.41 PATIENTPHOTOSTORAGE