This chapter describes how to install Convertigo Form Builder Standalone on premises

Convertigo Form Builder Standalone

This a is the dockerized version of Convertigo Form Builder that enables you to run it on premises.

Pre-requisites

Linux platform is recommended.

Installation guide

You can access the Form Builder Releases here

First of all, extract tar.gz (This file is given by a download link in a message) :

$ tar -xzvf c8oforms_standalone.tar.gz

Then, start docker as a deamon :

$ systemctl start docker

Then, make sure you have correct permissions on folder c8oforms_standalone (read/write/execute)

$ sudo chmod -R 777 ./c8oforms_standalone

Then, navigate to folder, and start-up docker :

$ cd c8oforms_standalone
$ docker-compose up -d

When its done, on first launch you must configure couchdb. You can either use init_couchdb.sh that configure for you automatically couchdb in single-node mode :

$ ./init_couchdb.sh

You can also configure it by using fauxton.

You have to wait about 5 minutes for the environment to finish setting up to start.

Go to Convertigo administration, into projects to check that all projects has been loaded. After 5 minutes you must see following projects:

Figure: Projects Form Builder

Convertigo projects used by Convertigo Form Builder are:

  • C8Oforms
  • lib_ExtendedComponents
  • lib_FullSyncGrp
  • lib_UserManager
  • lib_OAuth

To shutdown docker,and stop Convertigo Form Builder, run:

$ docker-compose down

Update guide

You can access the Form Builder Repository here :.

First of all, downlaod C8Oforms.car, and then Go to Convertigo administration, into projects to import your C8oForms.car

Click on Deploy a project, and then browse file on your system.

Figure: Deploy a project

Environment

Convertigo Form Builder

Convertigo Server

Couchdb fauxton

  • Connect to url: http://your_server:28081/_utils
    login: admin password: fullsyncpassword
  • The Couchdb directory which includes databases is in folder c8oforms_standalone/couchdb.

Workspace

  • You can find your workspace into folder c8oforms_standalone/workspace.
  • This workspace contains all Convertigo user data: the projects, the configuration files, the logs, etc.

Create a new Convertigo Form Builder account

Go to convertigo administration and login, then navigate to test platform, and click on lib_UserManager, execute sequence AddUser with user email and password.

Figure: CreateAccount Form Builder

Be careful to use an email like “myemail@mail.com”. If you don’t, you won’t be able to login.

Authentication Active directory

You have to configure project lib_UserManager . To do so go to convertigo admin console: http://your_server:28080/convertigo/admin/login.html and type login and password. Then, click on project on the left hand side to access to project list view. On the left side of lib_UserManager and C8Oforms projects, you will se a red warning icon, click on it to create symbols.

Figure: Symbols UserManager 1

Now that its done, click on symbols on the left hand side.

Figure: Symbols UserManager 2

For lib_UserManager, you will have to define 3 symbols:

  • lib_UserManager.adminUser
    • This user must be an active directory account, who has at least read only access right, and so can execute research on whole tree (expected synthax is DOMAIN_NAME\USER)
  • lib_UserManager.adminPassword.secret
    • Password of our active directory user
  • lib_UserManager.ldapServer
    • Url of LDAP server such as ldap://LDAP_SERVER:389

For C8Oforms, you will have to define 1 symbol:

  • C8Oforms.loginAdGroup
    • This group, is used to determine if an active directory user will be able to connect to Convertigo Forms. If symbol is empty, any Active directory user will have acess to Convertigo Forms, but if symbol is defined, only users that are members of this group will have acess to Convertigo Forms.

Add your certificates store

With default installation, a self-signed certificate is embedded. This configuration enables https connections but induces a security alert in your browser.

You can add your certificates store in c8oforms_standalone/tomcat/conf. If you don’t have a certificates store but the site certificate, you can insert it in certificates.jks by using specifics openssl and keytool.commands.

You have to modify the file c8oforms_standalone/tomcat/conf/server.xml.

In this file, find the following section:

<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
               maxThreads="150" scheme="https" secure="true"
               clientAuth="false" sslProtocol="TLS"
               keystoreFile="conf/certificates.jks" keystorePass="password" />

Change the keystoreFile with the name of your jks store and the keystorePass too.

The modification will be validated after a restart of the container :

$ docker-compose down
Stopping c8oforms_standalone_convertigo_1 ... done
Stopping c8oforms_standalone_couchdb_1    ... done
Removing c8oforms_standalone_convertigo_1 ... done
Removing c8oforms_standalone_couchdb_1    ... done
Removing network c8oforms_standalone_default
$ docker-compose up -d
Creating network "c8oforms_standalone_default" with the default driver
Creating c8oforms_standalone_couchdb_1 ... done
Creating c8oforms_standalone_convertigo_1 ... done

To see if your certificate store is correctly validated, look at the log files in c8oforms_standalone/tomcat/logs/catalina.date.log

Info log file, you have to find :

org.apache.coyote.AbstractProtocol.init Initializing ProtocolHandler ["https-jsse-nio-8443"]

with no exception after.

Backup

Directories to save in the event of a machine crash :

  • All the workspace directory except logs folder. This contains all the specifics parameters as well as the symbols set.
  • All the couchdb directory. This directory contains all the databases used for Convertigo Form Builder. In particular the definitions of forms, users, rights, …
  • The tomcat/conf directory, only if you have changed the configuration like add a certificate store.

Restoration is easy. It consists of replacing the installed directories with those saved. Note that backup can be done while CouchDB is running see this article in CouhcDB documentation Couchdb Backups

GDPR Compliance

They are two built in features in Convertigo Forms to help you comply with the General Data Protection Regulation - GDPR.

1) You can define a text (HTML is supported) to display in the GDPR menu of the application.

2) You can display a message each time a user creates a form, to make him aware of the GDPR rules.

To do this, Go to Convertigo administration, into symbols section, and create the following symbols:

  • C8Oforms.GDRP-MENU To define the text and show the GDPR menu (1)
  • C8Oforms.GDRP-TOAST To define and display the message before creating a new form (2)