Video tutorial

Windows Services

The openIMIS Windows Services are helping with the periodic activities which are required by the implementations.

Policy Renewal service

This Windows service periodically marks the policies that will expire in the near future to be renewed and updates the status of the already expired policies.

Download Policy Renewal service.

Backup service

This Windows Service periodically creates a backup of the database.

Download Backup service.

Install Windows Services

To install the Windows Service, proceed as follows for each Service:

1. Download and unzip the installation setup from the links mentioned in the available Services

2. Double click on the setup file

3. Select the installation path (for example C:\Program Files\openIMIS\Windows Services), and click Next

4. Close after the installation completes

The installed Service should start automatically as indicated in the system tray. If not, browse to Programs menu and search for the Service name (the controller of the service) and execute it.

Fix broken services

Fix initial configuration files

1. Run IMIS Policy Renewal (if an error window appears, click Continue)

2. Right-click the Policy Renewal icon in the system tray (lower-right corner of Windows) and click Settings

3. Fill the newly-created window Imis Renewal Policy as follows (please adapt to your situation):

   1. Server: .\SERVERNAME

   2. Database: openIMIS.1.3.0

   3. User Name: ImisUser

   4. Password: Pa$$w0rd

   5. Time: 00:00

   6. Interval: 24

   7. Untick all Send SMS to... options

   8. Click Apply

4. Make a copy of the file ImisPolicyRenewal.exe.config inside C:\Program Files\openIMIS\Windows Services within the same folder

5. Rename the copy into ImisBackup.exe.config

Fix service startup

1. Run Services

2. Locate ImisBackup and ImisPolicyRenewal, and do the following for each:

   1. Double-click the said entry

   2. Click the Log On tab

   3. Select the Local System account option

   4. Tick the Allow service to interact with desktop checkbox

   5. Click OK

   6. Right-click the said entry

   7. Click either Restart or Start (whichever is possible)

   8. Locate its icon in the system tray (lower-right corner of Windows)

   9. Right-click the said icon and click Settings

   10. Fix field values, if needed

Configure Windows Services

Configure the Imis Policy Renewal Windows Service

This service is used to update insurance policies and runs every day at the specified time. It will do the following actions:

1. If it finds a policy which is about to expire within a specified period of time, it flags it as to be renewed. The list of policies to be renewed can be used by the Enrolment Officers to contact the concerned families. The default policy expiring period of time is 14 days.

2. Sets the policy status to expired to all policies that have expired in between this Service runs.

3. Sends SMS to insuree if their policy is about to expire so that they can renew the policy (optional).

After the service installation, the user has to set the name of the server, the database name, the SQL-server instance credentials, and the service schedule for checking which policy is to be flagged as expired policy.

The days specified before the exact policy expiry date is provided in the table tblIMISDefaults under openIMIS Live database. The figure below shows the interface for Policy Renewal Service.

Under the SMS gateway setting, you need to specify the URL given by SMS Gateway provider. You also need to provide the username and password to allow the service to send SMS to the insuree.

Configure the Imis Backup Windows Service

This service is used for database backup, after the service installation, the user has to set the name of the server, the database name, the SQL-server instance credentials, and the service schedule for the backups.

The backup location is specified in the table tblIMISDefaults under openIMIS Live database. The figure below shows the interface for the database backup service.

The openIMIS Legacy Web Application allows managing your health financing processes through your browser. It is based on Microsoft technologies and can be used as a standalone application or be combined with the Modular Web Application. The following steps are presenting the processes of installation and customization of the Legacy Web Application to satisfy your implementation requirements and needs.

Video tutorial

Install Internet Information Services (IIS)

In Windows Server, follow these steps to install IIS:

1. In the Server Manager → Dashboard → Add Roles and Features

2. Select Role-based or feature-based installation

3. Select your server from the server pool, and select your server from the list

4. In Server Roles → select Web Server (IIS) → Add Features

5. In Features

   1. Select .NET Framework 3.5

   2. Select .NET Framework 4.6 and ASP.NET 4.6 (or later)

6. In Web Server Role (IIS) → Role Services

   1. In Web Server, ensure that Common HTTP Features → Static Content is ticked

   2. In Application Development, select .NET Extensibility, ASP, ASP.NET, ISAPI Extensions, ISAPI Filters and Websocket Protocol

   3. In Management tools, tick all boxes

7. Click on Install and wait for the features to be installed

8. Restart the server if required

Download openIMIS Web Application

Download and unzip the desired release from Github web_app_vb repository into a new folder under the IIS wwwroot (e.g. C:\inetpub\wwwroot\openIMIS.1.4.0).

Configure IIS

The configuration of IIS is done through Internet Information Service (IIS) Manager.

Add the openIMIS Site

In Internet Information Service (IIS) Manager:

1. Select your server name → Sites

2. Remove the Default Web Site (if new installation)

3. Right-click on Sites → Add Website

4. Enter a site name for your openIMIS instance (e.g. openIMIS.1.4.0)

5. Enter or select the physical pathname (e.g. C:\inetpub\wwwroot\openIMIS.1.4.0)

6. If you have an SSL certificate, select binding type to HTTPS (port 443) and select your certificate

7. If you don't have an SSL certificate, select binding type to HTTP (port 80)

If you have selected the binding type to HTTPS (port 443), then you will have to add also the binding type for HTTP

1. Right-click on the new added website

2. Select Edit Bindings

3. Select binding type HTTP (port 80) and click ok

If you have a DNS address (e.g. demo.openimis.org) that is mapped to your server IP address, you can add it in the site binding configuration as the hostname. This will allow having multiple Sites deserving same ports (80 and 443) and can be used to have, for example, openIMIS development (e.g. dev.openimis.org) and production (e.g. demo.openimis.org) sites on the same server.

Change Globalisation

Depending on the server’s initial configuration, the date format may differ from the expected DD/mm/YYYY format. To force the date format, go to the openIMIS site, then select Culture → .NET Globalisation, and select English (United Kingdom) (en-GB) as a culture.

Configure openIMIS Web Application

Edit the web.config

The web.config file provides the configuration for openIMIS Web Application, including database connection string and necessary folders.

To configure the database connection string, go in openIMIS root folder (e.g. C:\inetpub\wwwroot\openIMIS.1.4.0), locate the web.config file and edit IMISConnectionString entry so that the connection string points to the database created in openIMIS database section with the right credentials. For example:

<connectionStrings> 
    <add name="IMISConnectionString" connectionString="Data Source=WIN-H4E4ARREBFH\SQLEXPRESS;Initial Catalog=openIMIS.1.4.0;User ID=ImisUser;Password=password1234" providerName="System.Data.SqlClient" /> 
</connectionStrings>

Other configuration settings can be found within the <appSettings> tag and should be modified with caution.

Assign permission to source folders

openIMIS Web Application needs to have full right in certain folders. For this, IIS_IUSRS Windows user must have full control access to the following folders in openIMIS root folder (e.g. C:\inetpub\wwwroot\openIMIS.1.4.0):

• Archive

• Extracts

• FromPhone

• Images

• Workspace

Repeat the following steps for each folder listed above:

1. In Windows Explorer, right-click on the folder and select properties

2. Ensure that the folder is not read-only

3. Select the Security tab

4. Click on Edit

5. Select IIS_IUSRS and allow full control (in the below section).

6. Then apply and click OK.

Edit permissions to Windows event logs

Click on the Windows Start menu of run Regedit via the search box:

1. In the Registry Editor, select HKEY_LOCAL_MACHINE → System → CurrentControlSet → Services → Eventlog.

2. Right-click on the EventLog node, select Permission. Give full permissions to IIS_IUSRS, as described in the above paragraph (Assign permission to source folders). If the IIS_IUSRS user is not present in the list, then click Add button to add it manually.

3. Now repeat the same steps for Eventlog → Security and Eventlog → State node, as it can be required depending on the server’s environment.

Additional resources:

• How to fix permissions error on Windows event logs?

Open the Web Application

Open your Internet browser and type the following URL in the browser address bar: http://localhost/

If you have initiated the openIMIS Blank Database, use the following credentials:

• Login name: Admin

• Password: Admin

If you have initiated the openIMIS Demo Database, use the following credentials:

• Login name: Admin

• Password: admin123

Video tutorial

Minimum requirements

The minimum requirement to install and use openIMIS in a production environment are:

• Windows Server 2016

• 2 core CPU

• 8 GB RAM

• 100 GB Hard drive

• Administrator privileges

You can acquire a VPS from any hosting provider (e.g. Azure, AWS) or create your own server backbone.

For development and testing purposes, please follow the minimum requirements on the following tools:

• SQL Server minimal requirements

• Visual Studio 2017 minimal requirements (for other versions please check on Microsoft website)

openIMIS platform is composed of different components that allow the user to chose between Web-based and Mobile-based applications. This tutorial on Installation & Country Localisation has been developed based on this distinction and is composed of:

Video tutorial

Install SQL Server

When the installation wizard opens, select the manual configuration option in order to fine-tune the installation process.

On the Features selection:

1. In Shared Feature section, select SQL Client Connectivity SDK

2. For installations with Data Warehouse, select Analysis Services, Reporting Services and Integration Services (not available for the Express edition)

On the Instance configuration, the default name SQLEXPRESS can be used, unless it is already used by another instance.

On Database engine configuration, select Mixed Mode (SQL Server authentication and Windows authentication) in Authentication Mode.

Continue the setup process until the installation is complete.

Configure SQL Server

Open the SQL Server Configuration Manager.

On the left panel, select SQL Server Network Configuration → Protocols for SQLEXPRESS (or the name of your SQL Server instance) → Enable Named Pipes and TCP/IP.

Select SQL Server Services → right-click on SQL Server instance name and select Restart.

Initialize openIMIS database

If you wish to initialize the database using SSMS, follow the steps:

1. Create a new database for the openIMIS instance (e.g. openIMIS.1.4.0, where 1.4.0 is the openIMIS database version).

If you prefer to initialize the database using the shell, run the following command:

Create a dedicated user with full privilege on the openIMIS database only:

1. In the Security → Logins → right-click and select “New Login…”

2. In General page:

   1. Give a login name (e.g. ImisUser)

   2. Select SQL Server authentication and provide a password

   3. Unselect Enforce password expiration

   4. Change the default database to openIMIS

3. In User Mapping page:

   1. Map openIMIS database to ImisUser user

   2. Give the role of db_owner

Initialize specific openIMIS database

There are three specific openIMIS databases to chose from:

To initialize one of the specific openIMIS databases, follow the steps:

1. Initialize the openIMIS database by following the previous section steps

2. Run the specific database script on the already initialized openIMIS database

Upgrade the openIMIS database

During the upgrade make sure the is not reachable from the applications (you should stop the openIMIS website in Web Application IIS).

Duplicate the openIMIS database using SSMS (create a full backup of the database and restore it with another database name, e.g. openIMIS.1.4.0) or shell (see following command).

If you want to localise openIMIS Web Application component, you will need first to download the source code for the Web Application from .

The .NET Web Application has been developed to be used in different insurance contexts and with the idea of minimal adaptations. Most of the localisation can be realized through database change. However, there are some specific requirements that will have to change the Web Application's source code.

Video tutorial

Escape procedures localisation

The role of the Escape procedures is to allow adaptation of the Web Application to different insurance contexts. There are situated in a single class, EscapeBL, which makes it easier to access and modify without having to worry about messing with the whole Web Application source code. To modify the escape procedure, first download the source code from Github Web Application repository. Within the solution, go to IMIS_BL folder and open the EscapeBL.vb file.

There are 2 escape procedures that can be modified:

1. isValidInsuranceNumber allows validating the insuree number based on predefined rules. It is used, for example, when a new family or insuree are enrolled in openIMIS to ensure insuree number validity and to prevent typing errors.

2. SendSMS allows sending SMS messages through a specific SMS Gateway. It is used, for example, in Web Application Policy Renewal form to send the renewal SMS message to the family.

Localise the insuree number validation escape procedure

In this guide, we will localise the isValidInsuranceNumber method.

This is the generic implementation of the method:

Public Function isValidInsuranceNumber(ByVal InsuranceNumber As String) As Boolean 
    Return True 
End Function

The generic method is returning always true, meaning any insuree number will be a valid one.

Let's take for example the following insuree number requirements:

1. The insuree number must follow the modulo 9 rule: the last digit is the modulo 9 of the number without the last digit

2. The insuree number must have 10 digits ('0' at the beginning must be saved)

These requirements are satisfied by the following escape procedure:

Public Function isValidInsuranceNumber(ByVal InsuranceNumber As String) As Boolean 
    If Not InsuranceNumber.ToString.Length = 10 Then Return False 
    Dim N As String = Left(InsuranceNumber.ToString, 9) 
    Dim Modulo As String = Right(InsuranceNumber.ToString, 1) 
    If Modulo = N - (Int(N / 9) * 9) Then Return True 
    Return False 
End Function

The isValidInsuranceNumber is executing the following steps:

1. validates the length of the insuree number (line 2)

2. splits the insuree number into number and modulo parts (lines 3 and 4)

3. validates the insuree number if the modulo part is equal to the modulo result (line 5)

4. all other cases are invalidated (line 6)

Other validations rules can be applied.

To apply the new modification to the escape procedures, the Web Application .Net solution needs to be published and deployed.

Video tutorial

Language translation

Web Application .Net is supporting up to two languages. The language translation is done on the Web Application source code level (this page) and on the database level (see WA4.1 Language selection and translation tables).

The Web Application language localisation is using the default ASP.Net Globalization and Culture configuration. The translation is based on resource files. The generic application is translated into English-language and French-language.

In order to facilitate the translation of the Web Application and to have a common repository for language packs for openIMIS, we have subscribed to lokalise.com. If you wish to add new languages to openIMIS Web Application, you can request the access by visiting the Web Application project on lokalise. For more information on the translation platform please check Translation Management platform page.

Add a new language for Web Application in lokalise

Add new language to the project

From the Web Application project press the + button to add a new language.

From the Add languages modal select the language to add. You can filter the languages by writing in the input field. In this example, we will choose French (Cameroon). Multiple languages can be added at once.

Click the Add button.

Translate the glossary to the new language

From the Web Application project press the Glossary button to add a new language.

For each glossary term, translate in the new added language.

Translate the Web Application into the new language

For each term in the Web Application project, translate it in the new language.

Export the language as .Net resource file

From the Web Application project press the Download button.

Select the language you want to download and the different download settings.

Press Build and download button. This will download a ZIP file with resource files for all selected languages. Unzip the file in a local folder.

Add the new language in the Web Application project

Open in Visual Studio the Web Application .Net solution downloaded from Github.

In the Solution Explorer window, navigate to IMIS project → App_GlobalResources folder and open the contextual menu with right-click.

Select Add → Existing Item....

Select the resource file for the new language and press Add. This will copy the file to the App_GlobalResources folder and add it to the project.

(Optional) you can check the new language by opening the resource file.

To use the new language, the Web Application .Net solution needs to be published and deployed. Nevertheless, you cannot use the new language unless you update the language selection and translation tables in the database.

Why Glossary is important

Because there is multiple truth and it is often complex and can change over time, the terminology must have the same meaning and same wording in the whole Web Application. It is also important that the country-specific names are validated by the country implementing openIMIS.

When using a glossary you ensure that you will use the same 'truth' across your application. In the case of lokalise, every time it will detect the glossary term, it will show the definition and the translation, allowing to be consistent in the translation package.

For example, in Tchad there are the different organisation names which must be adapted in openIMIS:

Video tutorial

Publish and deploy the Web Application

In the previous sections, we have seen how to update the escape procedures and to add new language translation. In this section, we will publish the new customised Web Application in a folder and deploy it over the previously installed generic version.

Publish the customised Web Application

For detailed documentation on publishing using Visual Studio, visit the how to deploy to a local folder webpage.

Open in Visual Studio the Web Application .Net solution updated in the previous steps.

In Solution Explorer, right-click the IMIS project and choose Publish (or use the Build > Publish menu item).

The default target location is the publish folder under the Web Application solution folder. If you wish to change the target location then you just edit the configuration.

Press the Publish button.

Deploy the Web Application

To deploy the localized Web Application published in the previous section, please follow the same steps from Web Application installation steps.

Deploy the Web Application as a new site

To deploy the Web Application as a new site, follow the steps from the Configure IIS section. You will need to change the binding ports or map different DNS as hostname.

Deploy the Web Application to upgrade existing site

To upgrade an existing Web Application site, replace existing files with the files from the published Web Application.

Please make sure to:

• not replace/remove Archive, Extracts, FromPhone, Images, and Workspace folders to prevent losing previous work

• update IMISConnectionString in Web.config file

• you don't need to edit permissions to Windows event logs again