Open Lowcode Operation Guide

This guide applies to Open Lowcode version 1.0.0 and further versions. You may also want to consult the Frequently Asked Questions.

The following operation procedures are documented

• Development Platform setup
• Application Architecture
• Server Installation Prerequisites
• Operation Procedures
  • Server Installation
  • Change the encryption key
  • Initial Configuration and server start
  • Test Database Installation
  • Stop Server
  • Restore Server after crash
  • Install serveral Servers on the same host

Development Platform setup

Prerequisites

To develop your application with Open Lowcode framework, you need the following prerequisites:

• installation of a java development environment version 8 with javafx. If you do not have an Oracle JDK installed, you may want to install zulu JDK
• A java IDE supporting java 8. Open Lowcode development uses Eclipse 18/09, so it may be easier for you to use Eclipse.

Installation

You will need to:

• create a project in your IDE. (In Eclipse File / New / Project, then choose java project in the wizard, and enter your project name (e.g. OpenLowcode Beta Test)
• Unzip the Open Lowcode zip file directly in the project folder. To perform that, you can:
  • Copy the beta zip file in the project root folder
  • If you have 7-Zip, Use the 7 Zip option Extract here
  • If you use standard Windows zip manager, click extract all, and be sure to remove the last element of the proposed classpath (highlighted in red) so that elements are unzipped under your Eclipse project folder directly
• Refresh the project (F5 in eclipse or right click as below)
• Add all the JARs in the lib folder inside your project classpath (Project / Properties / Build Path / Add Jar)
• Adapt the two batches (launchserver.bat and launchclient.bat) to the specifics of your environment. This includes especially adapting the java folder and javafxrt.jar path to your local installation. If java8 JDK is your main java installation, it may be OK to have only “java” in the command line.
• Create an automatic code generation configuration by:
  • using the Run Configuration
  • Configure a run configuration with the org.openlowcode.system.module.Module class and the sandbox project model (fully classified name) as parameter
• Run the automatic code configuration and refresh the project in Eclipse (F5 after having selected project)

Application Architecture

Open Lowcode is a 3-tier application framework. The diagram below shows the architecture. The application server requires the following components:

• Mandatory: a database server amongst supported databases;
• Mandatory: an inbound connection from clients (PCs of users) to the server;
• Optional: a SMTP mail server (to send mail notifications and invitations);
• Optional: a connection to enterprise LDAP to allow login with user enterprise password.

Server Installation Prerequisites

General Prerequisites

The Open Lowcode server requires the following to be setup:

• a database server with a supported database (see next paragraph). A user / schema should be setup for each Gallium server: The database user should have DDL (Data Definition Language) rights (create / update table / index…)
  • The database should be configured so that unicode text can be stored.
  • A backup service of the data should be setup. This will allow restoration of the Open Lowcode application in case of a server failure (see restore procedure)
  • JDBC connection (port) should be opened from the Open Lowcode server to the database
• A regular purge of the log folder (either delete or archive) should be setup. It is recommended to purge the log folder regularly as the server may generate several100MB of log data per week
• An inbound port to be opened from all final users PC network to the server. One port is necessary for each Gallium Server instance running on the PC. Note: this requires
• (Optional) An outbound SMTP port to the e-mail server if the mail notification service is used
• (Optional) A JNDI port opened to the LDAP server to use authentication with enterprise password.

Software Installation

Open Lowcode server requires the following components on the server:

• Java Runtime 1.8 (1.8.051 or further)
• JDBC jar of the database (to be installed in the /lib) folder
• Operating System: any Unix or Windows operating system able to support the software above

Supported Databases

Open Lowcode server supports the following databases:

• Derby embedded database engine (Apache Derby – 10.12.1.1 or further). This is most appropriate for a low cost development server. In this mode, there is only one database connection for the server, with performance limits.
• MariaDB version 10.2.6 or later 10.2. This is suitable for production usage.

Note: Other databases support can be added with a quick delay (around a week) by requesting it to Open Lowcode SAS for a fee, or alternatively by implementing necessary modifications yourself.

Operation Procedures

Server Installation

Change the encryption key

It is highly recommended to override the class holding the 2-ways encryption key. The procedure is described below

• Create a project with the 2 following JARS of Open Lowcode (OlcClient.jar, OlcServer.jar) in the lib folder
• Create a class org.openlowcode.tools.enc.OlcEncrypterString with the code as mentioned below (you can copy paste and change the key)

package org.openlowcode.tools.enc;
public class OLcEncrypterString {
	protected static String getEncryptionString() {
		return "YourNewKeyHere";
	}
}

• Rebuild the OLcClient.jar and OlcServer.jar. You will find below a sample ant file

<project default = "buildnewjar">
 <target name="compilekeyclass">
        	<javac encoding="utf-8" srcdir="./src" destdir="./bin" debug="true" debuglevel="source,lines,vars" >
			<include name="org/openlowcode/**" />			
		</javac>
 </target>
 <target name="buildnewjar" depends="compilekeyclass">
        <jar destfile="./lib/OLcServer.jar" update ="true">
        	<fileset dir="./bin/" includes="org/openlowcode/tools/enc/OLcEncrypterString.class" />
		</jar>
		<jar destfile="./lib/OLcClient.jar" update="true">
			<fileset dir="./bin/" includes="org/openlowcode/tools/enc/OLcEncrypterString.class" />
		</jar>
 </target>
 </project>

Initial Configuration and server start

To start the server, it is necessary to configure the launch batch to be adapted to the environment. Below is shown an example of launch file (called launchserver.bat) on Windows. The batch would be called launchserver.sh on an Unix environment.

java -classpath D:\java\ws\CSPData\lib\derby.jar;D:\java\lib\ext\jfxrt.jar;D:\java\ws\PT1\bin\OLcServer.jar;.\bin\;.\lib\javax.mail.jar;.\lib\commons-logging-1.2.jar;.\lib\fontbox-2.0.7.jar;.\lib\pdfbox-2.0.7.jar;.\lib\commons-collections4-4.2.jar;.\lib\commons-compress-1.18.jar;.\lib\poi-4.0.1.jar;.\lib\poi-ooxml-4.0.1.jar;.\lib\poi-ooxml-schemas-4.0.1.jar;.\lib\xmlbeans-3.0.2.jar org.openlowcode.server.runtime.OLcServer 
./log/ 
8080 bugkiller.app.Bugkiller;customersales.app.Customersales;gallium.pvts.Pvts 
true 
false
null 
SSLPASSWORDSMTP 
ssl0.ovh.net 
465 
nicolas@openlowcode.com 
<mailpassword> 
DERBY 
D:\java8\ws\CSPData\derby
OlcClient.jar

The launch file includes the classpath of the server (in blue above). The classpath should include:

• The specific application JARs to be deployed (to be precised by the development team)
• The Open Lowcode Server JAR (OLcServer.jar)
• the standard library elements for Javamail and apache PDFBox ( javax.mail.jar, commons-logging-1.2.jar, fontbox-2.0.7.jar, pdfbox-2.0.7.jar)
• the Apache POI libraries (commons-collections4-4.2.jar, commons-compress-1.18.jar, poi-4.0.1.jar, poi-ooxml-4.0.1.jar, poi-ooxml-schemas-4.0.1.jar, xmlbeans-3.0.2.jar)
• the JDBC library JAR for the database The following parameters have to be setup on the GalliumServer (in purple above):

Parameter	Explanation
logfolder	A valid path for the log folder. The application will try to create the log folder if it does not exist
port	port open to clients for socket connection
modulelist	list of module classes separated by ; . e.g. cspex.pj1.Module1;cspex.pj1.Module2. This has to be precised by the development team To configure the server with only the system module, put ‘null’ (without quotes) Note: the first module specified is the main module of the application. The system module does not need to be specified and is added by default
auditmessages	either true or false, if set to true, all messages to customers are put in log, increasing significantly log volume. It should be false for production
Reducedlogs	is either true or false: if true, only warning logs are put in logs. It should be true in production
LDAP	ldap server connection string for authentication, enter 'null' if LDAP not setup. If you have a user account, enter a string with the following syntax URL
smpttype	SIMPLESMTP or SSLPASSWORDSMTP or null
smtpserver	e.g. ssl0.ovh.net (if smtptype = SIMPLESMTP or SSLPASSWORDSMTP)
smtpport	e.g. 465 (parameter needed if smtptype = SIMPLESMTP or SSLPASSWORDSMTP)
user	e.g. blabla@toto.com (parameter neededif smtptype = SSLPASSWORDSMTP
password	For the SMTPSERVER (parameter needed if smtptype = SSLPASSWORDSMTP)
DBTYPE	either DERBY or MARIA10.2
URL	path of the folder if derby, JDBC full URL for MARIA10.2
Connection Pool Size	A figure of minimum 1 – e.g. 10 (not needed for DERBY)
User	jdbc database user (not needed for DERBY)
Password	jdbc database password (not needed for DERBY)
Client Jar	The name of the client jar to download. By default (no customized client), it should be OlcClient.jar

Test Database Installation

It is possible to test the database installation by running the following utility. It will test the following :

• DDL rights are given to the user
• Unicode is installed

java -classpath ./lib/OLcServer.jar;<JDBCJAR> gallium.server.runtime.TestDatabase <DBParameters>

is the path to the relevant database JDBC Jar, and are similar to the GalliumServer parameters :

Parameter	Explanation
DBTYPE	either DERBY or MARIA10.2
URL	path of the folder if derby, JDBC full URL for MARIA10.2
User	jdbc database user (not needed for DERBY)
Password	jdbc database password (not needed for DERBY)

Stop Server

To stop the server, you can use the java command below.

java -classpath ./lib/OLcServer.jar gallium.server.runtime.GalliumServerShutdown port

where port is the port of the server (e.g. 6000). The classpath requires the Open Lowcode server jar (OLcServer) with correct path.

Restore Server after crash

To restore after server crash, you should perform the following:

• restore the database
• launch the application server again. There is no persistence on server side so no need of special operation

Install serveral Servers on the same host

To install several servers on the same host for different applications, the following is required

• Mandatory: have an independent user / schema in the database for each server (each server will create its own tables with the same name, so the database configuration should make that possible). Alternatively, several databases can be used;
• Optional: Have a log folder for each server (for the sake of clarity);
• Mandatory: specify a port for each server. Each server can then be launched and shutdown independently. The only dependency will be the common database if configured so. Note: this is not a procedure to have several servers for the same application