Technical Manual | CMDBuild

» Technical Manual

January 2022

Author Tecnoteca srl

www.tecnoteca.com

ENG

www.cmdbuild.org

Version

3.4

Technical Manual

No part of this document may be reproduced, in whole or in part, without the express written permission

of Tecnoteca s.r.l.

CMDBuild ® uses many great technologies from the open source community:

PostgreSQL, Apache, Tomcat, Eclipse, Ext JS, JasperSoft, JasperReports, IReport, Enhydra Shark,

TWE, OCS Inventory, Liferay, Alfresco, GeoServer, OpenLayers, Quartz, BiMserver.

We are thankful for the great contributions that led to the creation of these products.

CMDBuild ® is a product of Tecnoteca S.r.l. which is

responsible of software design and development, it's the official maintainer

and has registered the CMDBuild logo.

CMDBuild ® is released under AGPL open source license (http://www.gnu.org/licenses/agpl-3.0.html)

CMDBuild ® is a registered trademark of Tecnoteca Srl.

Every time the CMDBuild® logo is used, the official maintainer "Tecnoteca srl" must be mentioned; in

addition, there must be a link to the official website:

http://www.cmdbuild.org.

CMDBuild ® logo:

• cannot be modified (color, proportion, shape, font) in any way, and cannot be integrated into

other logos

• cannot be used as a corporate logo, nor the company that uses it may appear as author / owner

/ maintainer of the project

• cannot be removed from the application, and in particular from the header at the top of each

page

The official website is http://www.cmdbuild.org

CMDBuild – Open Source Configuration and Management Database Page 2

Technical Manual

Contents

1. Introduction................................................................................................................................. 5

1.1. The application.................................................................................................................................... 5

1.2. Official website..................................................................................................................................... 6

1.3. CMDBuild modules.............................................................................................................................. 6

1.4. Available manuals................................................................................................................................ 6

1.5. Applications based on CMDBuild.........................................................................................................6

2. System configuration................................................................................................................... 8

2.1. Hardware requirements....................................................................................................................... 8

2.2. Software requirements......................................................................................................................... 8

2.3. Client requirements............................................................................................................................ 10

3. Installing CMDBuild...................................................................................................................11

3.1. Getting started................................................................................................................................... 11

3.2. CMDBuild installation......................................................................................................................... 11

3.3. CMDBuild installation via GUI (Windows and Linux).........................................................................11

3.4. CMDBuild manual installation (Linux and Windows)..........................................................................16

3.5. CMDBuild database configuration via Db Config Wizard (Linux and Windows).................................16

3.6. CMDBuild manual database configuration for Windows....................................................................17

3.7. CMDBuild manual database configuration for Linux..........................................................................18

4. CMDBuild version update..........................................................................................................19

4.1. CMDBuild update............................................................................................................................... 19

5. Configuration to access a DMS through CMIS..........................................................................20

5.1. Introduction........................................................................................................................................ 20

5.2. Configuration of categories management..........................................................................................20

5.3. Configuration of the DMS in CMDBuild..............................................................................................22

6. Backup of CMDBuild data.........................................................................................................24

6.1. Database backup............................................................................................................................... 24

6.2. Database restore............................................................................................................................... 24

7. Backup of Alfresco data.............................................................................................................25

7.1. Backup schedule............................................................................................................................... 26

8. Authentication modes................................................................................................................27

8.1. Introduction........................................................................................................................................ 27

8.2. Configuration of the authentication type.............................................................................................27

8.3. Configuring LDAP authentication....................................................................................................... 30

8.4. Single sign on configuration through CAS.........................................................................................30

9. Mobile interface activation.........................................................................................................31

9.1. Introduction........................................................................................................................................ 31

9.2. Components and architecture............................................................................................................ 31

9.3. Compatibility...................................................................................................................................... 31

9.4. Limitation of use................................................................................................................................. 32

10. GUI Framework activation.......................................................................................................33

10.1. Introduction...................................................................................................................................... 33

10.2. Configuration................................................................................................................................... 33

11. GeoServer............................................................................................................................... 35

11.1. Geo Server introduction................................................................................................................... 35

11.2. Installing Geo Server....................................................................................................................... 35

CMDBuild – Open Source Configuration and Management Database Page 3

Technical Manual

11.3. Configuring GeoServer in CMDBuild...............................................................................................35

12. BIM.......................................................................................................................................... 36

12.1. Introduction...................................................................................................................................... 36

12.2. BIMServer introduction.................................................................................................................... 36

12.3. Installation........................................................................................................................................ 36

12.4. Xeokit introduction........................................................................................................................... 38

13. CMDBuild configuration in cluster mode..................................................................................40

13.1. Cluster introduction.......................................................................................................................... 40

13.2. Cluster configuration........................................................................................................................ 41

13.3. Configuring the load balancer on Apache........................................................................................ 42

13.4. Check if the Cluster is working.........................................................................................................42

13.5. Applying patches in Cluster mode...................................................................................................42

14. Appendix: Glossary.................................................................................................................43

CMDBuild – Open Source Configuration and Management Database Page 4

Technical Manual 1. Introduction

1. Introduction

1.1. The application

CMDBuild is an open source web environment for the configuration of custom applications for the

Asset Management.

On the one hand, it provides native mechanisms for the administrator, implemented in a "core"

code which has been kept separated from the business logic, so that the system can be configured

with all its features.

On the other hand, it generates dynamically a web interface for the operators, so that they can

keep the asset situation under control and always know their composition, detachment, functional

relations and how they update, in order to manage their life-cycle in a comprehensive way.

The system administrator can build and extend his/her own CMDB (hence the name of the project),

modeling the CMDB according to the company needs; a proper interface allows you to

progressively add new classes of items, new attributes and new relations. You can also define

filters, "views" and access permissions limited to rows and columns of every class.

Using external visual editors, the administrator can design workflows, import them into CMDBuild

and put them at operators' disposal, so that they can execute them according to the configured

automatism.

In a similar way, using external visual editors, the administrator can design various reports on

CMDB data (printouts, graphs, bar code labels, etc.), import them into the system and put them at

operators' disposal.

The administrator can also configure some dashboards made up of charts which immediately show the

situation of some indicators in the current system (KPI).

A task manager included in the user interface of the Administration Module allows you to schedule

various operations (process starts, e-mail receiving and sending, connector executions) and various

controls on the CMDB data (synchronous and asynchronous events). Based on their findings, it sends

notifications, starts workflows and executes scripts.

Thanks to document management systems that support the CMIS standard (Content Management

interoperability Services) - among which there is also the open source solution Alfresco - you will

be able to attach documents, pictures, videos and other files.

There is also a Scheduling, which can be supplied both automatically when filling in a data card

and manually. This Scheduling will manage single or recurring deadlines related, for example, to

certifications, warranties, contracts with customers and suppliers, administrative procedures, etc.

Moreover, you can use GIS features to geo reference and display assets on a geographical map

(external map services) and / or on vector maps (local GeoServer and spatial database PostGIS)

and BIM features to view 3D models (IFC format).

The system also includes a REST web service, so that CMDBuild users can implement custom

interoperability solutions with external systems.

Furthermore, CMDBuild includes two external frameworks:

• the Advanced Connector CMDBuild, which is written in Java and can be configured in

Groovy: it helps the implementation of connectors with external data sources, i.e automatic

inventory systems, virtualization or monitoring ones (supplied with non-open source license

to the users that subscribe the annual Subscription with Tecnoteca)

• the GUI Framework CMDBuild, which helps the implementation of additional graphical

CMDBuild – Open Source Configuration and Management Database Page 5

Technical Manual 1. Introduction

interfaces, i.e. web pages (simplified for non technicians) that have to be published on

external portals and that are able to interact with the CMDB through the REST web service

CMDBuild includes a mobile interface (for smartphone and tablet). It is implemented as multi-

platform app (iOS, Android) and is able to interact with the CMDB through the REST web service

(supplied with non-open source license to the users that subscribe the annual Subscription with

Tecnoteca).

CMDBuild is an enterprise system: server-side Java, web Ajax GUI, SOA architecture (Service

Oriented Architecture), based on web service and implemented by using the best open source

technologies and following the sector standards.

CMDBuild is an ever-evolving system, which has been released for the first time in 2006 and

updated several times a year in order to offer more features and to support new technologies.

1.2. Official website

CMDBuild has a dedicated website: http://www.cmdbuild.org

The website gathers a lot of documents on technical and functional features of the project:

brochures, slides, manuals (see next paragraph), testimonials, case histories, newsletters, forums.

1.3. CMDBuild modules

The CMDBuild application includes two main modules:

• the Administration Module for the initial definition and the next changes of the data model

and the base configuration (relation classes and typologies, users and authorization,

dashboards, upload report and workflows, options and parameters)

• the Management Module, used to manage cards and relations, add attachments, run

workflow processes, visualize dashboards and execute reports

The Administration Module is available only to the users with the "administrator" role; the

Management Module is used by all the users who view and edit data.

1.4. Available manuals

This manual is for those who need certain first introductory information on CMDBuild and who are

interested in knowing the general philosophy of the project.

You can find all the manuals on the official website (http://www.cmdbuild.org):

• system overview ("Overview Manual")

• system usage for operators (“User Manual”)

• system administration ("Administrator Manual")

• workflow configuration (“Workflow Manual”)

• webservice details and configuration (“Webservice Manual”)

1.5. Applications based on CMDBuild

Tecnoteca has used the CMDBuild environment in order to implement two different pre-configured

solutions:

•

CMDBuild R

EADY

, for the management of assets and IT services, oriented to internal IT

infrastructures or services for external clients (http://www.cmdbuild.org/it/prodotti/ready2use)

according to the ITIL best practice (Information Technology Infrastructure Library)

•

openMAINT, for the inventory management of assets, properties and related maintenance

CMDBuild – Open Source Configuration and Management Database Page 6

Technical Manual 1. Introduction

activities (http://www.openmaint.org)

Both applications are released with open source license, except for certain external components

(data sync connectors, Self-Service portal, mobile APP, etc.), that are reserved to the users that

subscribe the annual Subscription with Tecnoteca.

CMDBuild – Open Source Configuration and Management Database Page 7

Technical Manual 2. System configuration

2. System configuration

In the following paragraphs the software requirements needed by the CMDBuild system and how

to install and configure its components will be presented.

When planning the system configuration, information security issues must be taken into account.

The activation of a web application like CMDBuild demands the availability of hardware and

network components with suitable levels of security. This is required in order to avoid unwanted

external accesses (firewall, DMZ) and to deliver a good system on-line availability and suitable

response times.

2.1. Hardware requirements

For the CMDBuild installation a physical or virtual server is required, with the following

characteristics:

• recent generation CPU

• a minimum of 8 GB of RAM, 16 GB if there will be an intensive usage of additional

functionalities, such as DMS, map server, BIM server.

• minimal disk storage 120 GB, it should be much higher if you need to manage extensive

archives of documents (fed by the management of the attachments).

We also advise that:

• the disk storage should be in RAID configuration

• the CMDBuild system data should be backed up daily

• an available UPS in order to avoid sudden electric power failures

2.2. Software requirements

CMDBuild installation and use require the following software components.

Operating system

Every operative system that supports JVM and the needed software will support CMDBuild.

Linux operating system is suggested because CMDBuild is more extensively tested on it.

Database

PostgreSQL from version 10 to version 12 (recommended version) is required.

You should check whether "plpgsql" is active and whether the database is set with an UTF-8

encoding.

CMDBuild uses the library "tomcat-dbcp" to connect to the database, this library is distributed with

Tomcat but is not included in some Linux distributions. In such cases the library can be found in

the official Tomcat distribution or in the extras/tomcat-libs/{Tomcat version dir} folder inside the

CMDBuild zip file; the library must be placed in /usr/share/{Tomcat version dir}/lib.

CMDBuild supports only the PostgreSQL database, because it is the only one that implements the

functionality of "derivation" of tables in the "object oriented" meaning. This is used for managing

CMDBuild – Open Source Configuration and Management Database Page 8

Technical Manual 2. System configuration
the sub classes and for managing the history of cards. 
If you use the GIS features of CMDBuild you have to also install the PostGIS spatial extension for 
PostGRES. If you require support installing and configuring PostGIS refer to postgis official docs 
and support: http://www.postgis.net/install
Servlet Container / Web Server
CMDBuild needs Apache Tomcat 8.5 or more recent (suggested Tomcat 9.0.30).
If CMDBuild is installed via GUI a fresh tomcat installation will be provided.
In   order   to   support   the   UTF-8   characters   when   using   attachments   (see  Installation   of   DMS
system), edit the configuration file “server.xml” and specify the attribute URIEncoding="UTF-8" for
the main "Connector" element.
You can use the web server Apache 2.2 in order to access many CMDBuild instances through
virtual hosts supporting different domains.
Reference Web site for both: http://www.apache.org/
Document Management System (DMS)
Any DMS that supports the CMIS protocol can be installed for the Document Management System
functionalities (that are optional).
Alfresco is the suggested DMS.
Reference website: http://www.alfresco.com/
Java Libraries
The Java Libraries are required by Apache Tomcat.
CMDBuild requires java 17.
Reference website: http://www.   oracle   .com/   
Libraries included in the release
The CMDBuild file downloadable from the project website contains some libraries already inside
the installation package, namely:
• the library for the JDBC connection to the PostgreSQL database 
• the Jasper Reports libraries for the production of reports (http://www.jasperforge.org/)
• TWS Together Workflow Server 4.4 libraries which implement the workflow engine used by
CMDBuild (http://www.together.at/prod/workflow/tws)
• the webservice available from the DMS Alfresco system in order to use its repository (http://
www.alfresco.com/)
• the ExtJS libraries for the generation of the Ajax user interface (http://extjs.com/)
• the   server   and   client   components   for   the   publication   of   geo   referenced   cartography
(http://geoserver.org/ e http://openlayers.org/)
• the server and client components for the visualization of BIM components
In order to design custom reports, you can use the visual editor Jasper Studio (6.x) or IReport
(version 5.x), which produce their descriptor in compatible format with the Jasper Reports engine
CMDBuild – Open Source Configuration and Management Database  Page 9

Technical Manual 2. System configuration

(http://jasperforge.org/projects/ireport).

For designing personalized workflows we suggest using the visual editor TWE Together Workflow

Editor 4.4 (http://www.together.at/prod/workflow/twe). The editor produces in output an XPDL 2.0

file compatible with the Together Workflow Server 4.4 engine.

For integrating systems of automatic inventory we suggest using the OCS Inventory version 1.3.3

(http://www.ocsinventory-ng.org/).

Some functionalities of CMDBuild can be integrated as portlets within systems compatible with

Portal JSR, among them Liferay version 6.0.6 or more recent (http://www.liferay.com/).

All software listed above are released with an Open Source license (the operating system is not

included if you choose to not use the Linux operating system).

2.3. Client requirements

Every interaction made with CMDBuild (using, administrating, updating the system and structuring

the database) is made via web application.

This means that the user, in order to interact with the system, will be required to have a recent

generation web browser installed (supported browser: Mozilla Firefox, Google Chrome, Microsoft

Explorer 11, Microsoft Edge, Apple Safari).

The web architecture ensures complete usability to any IT organization that operates in multiple

locations (ie collaborative workflow); any entrusted client can connect and interact with the system

using a standard web browser.

CMDBuild – Open Source Configuration and Management Database Page 10

Technical Manual 3. Installing CMDBuild

3. Installing CMDBuild

3.1. Getting started

CMDBuild can be installed in different ways, the installation via GUI is suggested. Anyhow the

following list of software are required before the installation:

• PostgreSQL database (it must be started and accessible)

• Tomcat application server (only if manual installation is performed)

• the DMS Alfresco (or others supporting the CMIS protocol, if you intend to use the

management of attached documents)

• the Java environment

As a first step is therefore necessary to ensure downloading and installing these products,

retrieving them from the links mentioned in the previous chapter.

Warning: you must to be careful to use directories not containing spaces within the entire path.

3.2. CMDBuild installation

After obtaining and installing the previously required programs we can proceed with the CMDBuild

installation.

The installations files are provided on the official CMDBuild website at the following link:

http://www.cmdbuild.org/en/download/

A .war file is provided to proceed with both graphical or manual installation.

3.3. CMDBuild installation via GUI (Windows and Linux)

To simplify the standard installation and configuration of CMDBuild, a guided GUI installation has

been provided for both windows and unix operating systems.

Once having downloaded the .war file open a terminal (on linux) or a cmd window (on windows)

and move to the folder containing the .war file. To run the GUI type the following command:

java -jar cmdbuild.war -v

This command will launch the graphical interface like in the following screenshot:

By clicking “install CMDBuild V3” we’ll be taken to the first configuration steps:

CMDBuild – Open Source Configuration and Management Database Page 11

Technical Manual 3. Installing CMDBuild

CMDBuild – Open Source Configuration and Management Database Page 12

Technical Manual 3. Installing CMDBuild

In this form we can decide the basic configuration of CMDBuild, the various field are now

described:

• Tomcat dir: the path where to install a fresh tomcat

• Tomcat port: the port that tomcat will use to communicate

• Database type: two basic databases are presented, an empty one where only the basic

structure is presented but no data is added, or a demo one where other than the basic

structure some data are added in for demonstration purposes

• Database host: the host where to install tomcat, localhost if we want to run it on our

machine

• Database port: the port used to communicate to the database

• Database name: the name of the database that will be created

• Database user: the basic user of the database, default: cmdbuild

• Database password: the basic user password of the database, default: cmdbuild

• Database admin user: the admin user of the database, default: postgres

• Database admin password: the admin user password of the database, default: postgres

A good practice is to test the configuration with the button “Test Config”, if everything is correctly

configured the following pop-up will appear:

CMDBuild – Open Source Configuration and Management Database Page 13

Technical Manual 3. Installing CMDBuild

We can now proceed with the “INSTALL” button.

Apache tomcat and CMDBuild will be installed, also the selected database will be loaded:

As soon as the installation will be completed a pop-up will ask us if we want to start the application

or not:

CMDBuild – Open Source Configuration and Management Database Page 14

Technical Manual 3. Installing CMDBuild

By choosing yes Apache tomcat will load and the installer will notify us as soon as the application

is ready to be used:

CMDBuild – Open Source Configuration and Management Database Page 15

Technical Manual 3. Installing CMDBuild

3.4. CMDBuild manual installation (Linux and Windows)

If instead of the graphical installation we want to manually install and configure CMDBuild, a

different procedure has to be followed. First of all Apache Tomcat (and every required software

previously listed) has to be manually installed (check the chapter above for download links and

supported versions). Once Tomcat is successfully installed we can proceed with the manual

installation.

Note: if you are installing OpenMAINT you should replace the references to "cmdbuild" with

"openmaint".

The downloaded file (cmdbuild-3.4.war) contains the web application files that can be extracted in

the tomcat installation folder under /webapps/cmdbuild .

Doing this will provide us with a working CMDBuild installation, but no database has yet been

created.

To configure the database we can either use the database configuration wizard provided after the

first tomcat startup, or we can proceed with a manual configuration via command line.

3.5. CMDBuild database configuration via Db Config Wizard (Linux and

Windows)

As in CMDBuild version 2.5 or older, a wizard to perform the database configuration has been

provided for new CMDBuild installations.

After configuring and launching a tomcat instance with the cmdbuild webapp, by accessing the

application via browser we will be redirected to the database configuration page:

In this form we can configure the database with the following fields:

• Type: the database we want to configure, either one of the provided ones (demo, empty),

an existing one or from a file

CMDBuild – Open Source Configuration and Management Database Page 16

Technical Manual 3. Installing CMDBuild

• Name: the name used by postgres

• Host: postgres host

• Port: postgres port

• Username: standard postgres username (suggested cmdbuild)

• Password: standard postgres password (suggested cmdbuild)

• Admin username: administrator postgres username (suggested postgres)

• Admin password: administrator postgres password (suggested postgres)

Once every field has been compiled it is suggested to use the “Test database connection” to verify

the validity of the configuration, if no errors are displayed we can proceed by pressing the

configure button.

After a successful configuration a list of patches that have to be applied to the uploaded database

might be shown, by pressing “Apply patches” the system will proceed with the application.

As soon as the login page is displayed the system is ready to be used.

3.6. CMDBuild manual database configuration for Windows

If the OS in use is Windows, the database import has to be done manually either via software like

pgAdmin or via postgres command line, the dump file for the database is provided under WEB-INF/

sql/dump located in the webapp folder. If you want to load a dump which includes gis/postgis

features, refer to postgis docs for any issue regarding postgis configuration and/or postgis version

upgrade/migration.

Example of postgis installation with postgres 12 and postgis 3.x for Windows 10:

-Download and Install postgres 12 from the official website http://postgresql.org/download/windows

-Download and install postgis for postgres 12 from the official online repository:

http://download.osgeo.org/postgis/windows/pg12

Connect to the postgres database by using a software like pgadmin 4. As the default administration

user create a new user named cmdbuild with password. Next create a database for the user

cmdbuild, you can now reconnect to this database as user cmdbuild and create a gis schema:

create schema gis;

Ceate the postgis extension (note: you may have to grant superuser permissions to cmdbuild user

for this command; you should revoke superuser permission after):

create extension postgis schema gis;

You can now proceed with importing a database. We can use, for example, one of the dumps

provided with the CMDBuild installation.

By using pgadmin as user cmdbuild, we can perform a restore with cmdbuild as target database,

the import will generate various warnings that can be ignored, those are caused by some

duplicated information in the dump file and in the existing database (gis function and types).

After the process is completed the application can be executed by launching tomcat with the

startup file, remember that if the port or any tomcat configurations have to be changed, this can be

done by modifying the tomcat configuration file called server.xml in the folder

<tomcat_install_folder>/conf.

CMDBuild – Open Source Configuration and Management Database Page 17

Technical Manual 3. Installing CMDBuild

3.7. CMDBuild manual database configuration for Linux

For the linux systems the command that will be used is dbconfig, and it can be called by using the

cmdbuild.sh file in the webapp folder. This command can perform the creation of a new database

based on a dump, and other functions described in the other documentations.

At this point the demo database provided with the CMDBuild war file can be imported. To do so

you can use the dbconfig command like in the following:

bash webapps/cmdbuild/cmdbuild.sh dbconfig create demo -configfile /path/to/configfile

CMDBuild will now setup a new database with the name provided in the configuration and will load

the demo dump provided in the war file.

CMDBuild – Open Source Configuration and Management Database Page 18

Technical Manual 4. CMDBuild version update

CMDBuild version update

4.1. CMDBuild update

In order to update CMDBuild to a newer version follow this procedure:

• Turn off tomcat execution and backup any needed information (i.e. the database)

• Save any needed configuration from the configuration folder: <tomcat_installation_folder>/

webapps/<webapp_name>/WEB-INF/conf

• Delete the directory of your CMDBuild web application in tomcat

( <tomcat_installation_folder>/webapps/<webapp_name> )

• Unpack the war file of the newer version of CMDBuild in the same folder

• Clean your browser cache to make sure that everything is updated

When the application is next launched, on the login screen a pop-up notifying that there is a new

version installed will appear.

To restore the previously saved configurations tomcat has to be turned off again and the old

configurations have to be moved to the configuration folder.

CMDBuild – Open Source Configuration and Management Database Page 19

Technical Manual 5. Configuration to access a DMS through CMIS

5. Configuration to access a DMS through CMIS

5.1. Introduction

CMDBuild allows the integration with any document management system that supports CMIS, an

open standard to exchange document data through the web protocol, supported by all the main

products of the sector.

The acceptance of such protocol allows to support base features to:

• Attach any kind of file to any data card

• Assign a category to every file

• Display the uploaded files

The management of categories and metadata at the moment is supported only for the protocol

CMIS 1.1, but CMDBuild supports even DMS based on CMIS 1.0. In case of the need for

categories and metadata a DMS based on CMIS 1.1 has to be used.

5.2. Configuration of categories management

In this section you will learn how to configure a DMS that can support the protocol CMIS 1.1, in

order to manage the classification of attachments when updating and refreshing them on

CMDBuild cards.

Here’s an example of the configuration for Alfresco 5.0.

Note that the names used here are unbinding.

To setup some custom categories with alfresco, two files have to be created and saved in the

alfresco folder:

${ALFRESCO_HOME}/tomcat/shared/classes/alfresco/extension

1) cmdbuild-model-context.xml

<?xml version='1.0' encoding='UTF-8'?>

<!DOCTYPE beans PUBLIC '-//SPRING//DTD BEAN//EN'

'http://www.springframework.org/dtd/spring-beans.dtd'>

<beans>

<bean id="example.dictionaryBootstrap" parent="dictionaryModelBootstrap" depends-

on="dictionaryBootstrap">

<list>

<value>alfresco/extension/cmdbuild-model.xml</value>

</list>

</property>

</bean>

</beans>

CMDBuild – Open Source Configuration and Management Database Page 20

Technical Manual 5. Configuration to access a DMS through CMIS

2) cmdbuild-model.xml

<?xml version="1.0" encoding="UTF-8"?>

<!-- The important part here is the name - Note: the use of the my: namespace

which is defined further on in the document -->

<description>Custom Model for CMDBuild</description>

<author>CMDBuild Team</author>

</imports>

<!-- NOTE: The following namespace my.new.model should be changed to reflect your own

namespace -->

</namespaces>

<title>Classfication</title>

</property>

</properties>

</aspect>

</aspects>

</model>

CMDBuild – Open Source Configuration and Management Database Page 21

Technical Manual 5. Configuration to access a DMS through CMIS

5.3. Configuration of the DMS in CMDBuild

Via REST commands the configurations of the DMS on CMDBuild can be changed, either via

editconfig rest command to open a gui showing all the available configurations (if CMDBuild is on

the local machine) or via setconfig/setconfigs rest command, in example:

cmdbuild.sh restws setconfig org.cmdbuild.dms.enabled true

General configs:

Config Type Description

org.cmdbuild.dms.enabled Boolean Enables or disables the DMS service

org.cmdbuild.dms.service.type String DMS service type (cmis, postgres,

sharepoint_online); cmis is a standard protocol

used, for example, by Alfresco dms; postgres is

an embedded dms implementation that relies

upon cmdbuild postgres db

org.cmdbuild.dms.category.lookup String Sets the base lookup DMS category

org.cmdbuild.dms.regularAttachments.ma

xFileSize

Int Maximum allowed file size, expressed in MB

org.cmdbuild.dms.incomingEmailAttachm

ents.allowedFileExtensions

List<String> Allowed file extensions, lowercase, for incoming

email (rejected attachments will be ignored and

print a warning, without affecting email

processing)

org.cmdbuild.dms.autolink.path String Autolink base path (replaces dms provider base

path, for links)

org.cmdbuild.dms.autolink.script String Autolink helper script

CMIS related configs:

Config Type Description

org.cmdbuild.dms.service.cmis.user String CMIS service username

org.cmdbuild.dms.service.cmis.password String CMIS service password

org.cmdbuild.dms.service.cmis.path String CMIS service path

org.cmdbuild.dms.service.cmis.url String CMIS service URL

Sharepoint related configs:

Config Type Description

org.cmdbuild.dms.service.sharepoint.user String Sharepoint service username

org.cmdbuild.dms.service.sharepoint.password String Sharepoint service password

org.cmdbuild.dms.service.sharepoint.url String Sharepoint service URL

org.cmdbuild.dms.service.sharepoint.path String Sharepoint service path

CMDBuild – Open Source Configuration and Management Database Page 22

Technical Manual 5. Configuration to access a DMS through CMIS

org.cmdbuild.dms.service.sharepoint.graphApi.

url

String Sharepoint graph api service URL

org.cmdbuild.dms.service.sharepoint.auth.servi

ceUrl

String Sharepoint authentication service url

org.cmdbuild.dms.service.sharepoint.auth.clien

tId

String Sharepoint authentication client Id

org.cmdbuild.dms.service.sharepoint.auth.clien

tSecret

String Sharepoint authentication client secret

org.cmdbuild.dms.service.sharepoint.auth.prot

ocol

String Sharepoint authentication protocol

org.cmdbuild.dms.service.sharepoint.auth.reso

urceId

String Sharepoint authentication resource Id

org.cmdbuild.dms.service.sharepoint.auth.tena

ntId

String Sharepoint authentication tenant Id

org.cmdbuild.dms.service.sharepoint.model.aut

horColumn

String Sharepoint model author mapping column

org.cmdbuild.dms.service.sharepoint.model.cat

egoryColumn

String Sharepoint model category mapping column

org.cmdbuild.dms.service.sharepoint.model.de

scriptionColumn

String Sharepoint model description mapping column

CMDBuild – Open Source Configuration and Management Database Page 23

Technical Manual 6. Backup of CMDBuild data

6. Backup of CMDBuild data

6.1. Database backup

In CMDBuild every information is stored in the PostgreSQL Database, so in order to perform a

backup of the information we need to backup the database.

Various ways can perform a backup of the database, programs like PgAdmin can perform this

action with the support of a graphical interface. Otherwise PostgreSQL provides a function to

perform a database backup.

In example:

pg_dump --host localhost --port 5432 --username “postgres” --format custom --

verbose --file /backup/cmdbuild/cmdbuild.backup cmdbuild_db

This command will create a backup of the database with the name “cmdbuild.backup”. This file will

be the backup of the database “cmdbuild_db” on the PostgreSQL installed on localhost at port

5432, performing the authentication as the user “postgres”, compressing the database with a

custom format and notifying the user with what the program is executing (with the verbose

parameter).

The location of where the backup file will be saved is /backup/cmdbuild.

6.2. Database restore

A backup can be restored at any time with a simple procedure.

CMDBuild provides different functions to perform various actions, such as database related

actions.

If the purpose is to restore a backup this command will restore the previously saved backup by

dropping the current database and creating a new one:

bash webapps/cmdbuild/cmdbuild.sh dbconfig recreate /path/to/database/backup.backup

CMDBuild – Open Source Configuration and Management Database Page 24

Technical Manual 7. Backup of Alfresco data

7. Backup of Alfresco data

To backup data in Alfresco you just have to backup the PostgreSQL database (hereafter we will

assume that it is in the database PostgreSQL).

As for CMDBuild, the command to backup the database on command line is as follows:

pg_dump --host localhost --port 5433 --username "postgres" --format custom --

verbose --file /backup/alfresco/alfresco.backup alfresco_db

It is also necessary backup - as zip or tar.gz file - also the whole directory containing the

repository where files are saved (e.g.: C:/alfresco/repository for Windows systems or

/var/alfresco/repository for *nix systems).

#!/bin/sh

ALFRESCO_SERVICE="/etc/init.d/alfresco"

TT_PG_BACKUP="/usr/local/bin/tt_pg_backup.sh"

BACKUP_HOME="/backup"

ALFRESCO_BACKUP_HOME="${BACKUP_HOME}/alfresco"

BACKUP_LOG="/var/log/cmdbuild/crontab-backup.log 2>&1"

ALFRESCO_DATABASE="alfresco"

ALFRESCO_DATA="/var/lib/alfresco/data"

TIMESTAMP=`date +%Y%m%d%H%M%S`

ALFRESCO_DATA_BACKUP="alfresco-data-${TIMESTAMP}.tar.gz"

logger "Stopping Alfresco service"

${ALFRESCO_SERVICE} stop

sleep 5

logger "Backupping Alfresco database"

${TT_PG_BACKUP} "${ALFRESCO_BACKUP_HOME}" "${ALFRESCO_DATABASE}" > ${BACKUP_LOG}

logger "Backupping Alfresco data"

tar czf "${ALFRESCO_BACKUP_HOME}/${ALFRESCO_DATA_BACKUP}" ${ALFRESCO_DATA}

logger "Alfresco database/data have been backed up."

logger "Starting Alfresco service"

${ALFRESCO_SERVICE} start

CMDBuild – Open Source Configuration and Management Database Page 25

Technical Manual 7. Backup of Alfresco data

7.1. Backup schedule

To schedule a periodical data backup on Linux systems, we suggest you to go on as follows:

1. create a /etc/cron.d/backup file

2. insert the commands into the backup file, with the proper cron syntax.

For a more efficient cleaning we recommend you to create various single scripts, one for each

system, and call them in this file rather than write the commands directly into the cron file itself.

An example:

00 19 * * * root /usr/local/bin/tt_pg_backup.sh /backup/cmdbuild cmdbuild

&>> /var/log/cmdbuild/backup/backup.log

10 19 * * 7 root /usr/local/bin/alfresco-backup.sh &>>

/var/log/cmdbuild/backup/backup.log

CMDBuild – Open Source Configuration and Management Database Page 26

Technical Manual 8. Authentication modes

8. Authentication modes

8.1. Introduction

Thanks to proper configurations of CMDBuild, the authentication control can be delegated to

external services.

This possibility concerns the control of the account (username and password). Profiles and

permissions will still be managed withing the CMDBuild group to which the user belongs.

Via REST commands the configurations of the authentication can be changed, either via editconfig

rest command to open a gui showing all the available configurations (if CMDBuild is on the local

machine) or via setconfig/setconfigs rest command, in example:

cmdbuild.sh restws setconfig org.cmdbuild.auth.case.insensitive true

8.2. Configuration of the authentication type

CMDBuild supports the following authentication methods:

• Default authentication

• SSO CAS authentication

• SSO SAML authentication

• Oauth2 authentication

The default authentication can be configured to utilize two different user repository:

• DB stored credentials

• LDAP system

In addition there are the following additional authentication methods:

• RSA authentication

• Header authentication

• Custom login (similar to header auth but with a control script addition)

To configure which type or types of authentication to use, from version 3.4, it is possible to specify

different auth modules with the following configuration schema

Config Type Description

org.cmdbuild.auth.modules String List of auth module names

org.cmdbuild.auth.modules.{ModuleName}.type String Authentication type for the specified

{ModuleName}

org.cmdbuild.auth.modules.{ModuleName}.description String Auth module description, shown in auth

org.cmdbuild.auth.modules.{ModuleName}.enabled Boolean Specifies if the module is enabled or not

org.cmdbuild.auth.modules.{ModuleName}.hidden Boolean Specifies if the module is hidden or not, if

hidden it’s only used by passing

cm_login_module in the request

CMDBuild – Open Source Configuration and Management Database Page 27

Technical Manual 8. Authentication modes

org.cmdbuild.auth.modules.{ModuleName}.... String Additional configurations for the specified

{ModuleName}

org.cmdbuild.auth.modules.{ModuleName}.type can have the following values as specified above:

• Default authentication

• SSO CAS authentication

• SSO SAML authentication

• Oauth2 authentication

CAS related configs:

Config Type Description

org.cmdbuild.auth.module.cas.server.url String CAS service URL

org.cmdbuild.auth.module.cas.login.page String CAS url login page

org.cmdbuild.auth.module.cas.service.param String CAS service parameter

org.cmdbuild.auth.module.cas.ticket.param String CAS service ticket parameter

SAML related configs:

Config Type Description

org.cmdbuild.auth.module.saml.handlerScript String SAML authentication response handler

script

org.cmdbuild.auth.module.saml.idp.cert String SAML idp certificate

org.cmdbuild.auth.module.saml.idp.id String SAML idp id URL

org.cmdbuild.auth.module.saml.idp.login String SAML idp login URL

org.cmdbuild.auth.module.saml.idp.logout String SAML idp logout URL

org.cmdbuild.auth.module.saml.logout.enabled Boolean SAML idp logout enabled flag

org.cmdbuild.auth.module.saml.requireSignedAssertions Boolean SAML require signed assertion flag

org.cmdbuild.auth.module.saml.requireSignedMessages Boolean SAML require signed messages flag

org.cmdbuild.auth.module.saml.signatureAlgorithm String SAML signature algorithm URL

org.cmdbuild.auth.module.saml.sp.baseUrl String SAML service provider base URL

org.cmdbuild.auth.module.saml.sp.cert String SAML service provider base certificate

org.cmdbuild.auth.module.saml.sp.id String SAML service provider id URL

org.cmdbuild.auth.module.saml.sp.key String SAML service provider private key

org.cmdbuild.auth.module.saml.strict String SAML service provider strict validation

flag

CMDBuild – Open Source Configuration and Management Database Page 28

Technical Manual 8. Authentication modes

Oauth related configs:

Config Type Description

org.cmdbuild.auth.module.oauth.clientId String OAuth client id

org.cmdbuild.auth.module.oauth.clientSecret String OAuth client secret

org.cmdbuild.auth.module.oauth.login.attr String OAuth login attribute to be matched with

cmdbuild users

org.cmdbuild.auth.module.oauth.login.type String OAuth login type matching (username or

email)

org.cmdbuild.auth.module.oauth.logout.enabled Boolean OAuth logout enabled flag

org.cmdbuild.auth.module.oauth.logout.redirectUrl String OAuth logout redirect URL

org.cmdbuild.auth.module.oauth.protocol String OAuth protocol (i.e. msazureoauth2)

org.cmdbuild.auth.module.oauth.redirectUrl String OAuth local url accepted from the provider

org.cmdbuild.auth.module.oauth.resourceId String OAuth resource id

org.cmdbuild.auth.module.oauth.scope String OAuth scope

org.cmdbuild.auth.module.oauth.serviceUrl String OAuth service URL

org.cmdbuild.auth.module.oauth.tenantId String OAuth tenant id

LDAP related configs:

Config Type Description

org.cmdbuild.auth.ldap.server.address String LDAP server address URL

org.cmdbuild.auth.ldap.server.url String LDAP server url (if set, will override server

host, port and ssl config); you may specify

multiple urls separated by one space

org.cmdbuild.auth.ldap.server.port Integer LDAP server port

org.cmdbuild.auth.ldap.basedn String LDAP base dn for user query

org.cmdbuild.auth.ldap.bind.attribute String LDAP user bind attribute

org.cmdbuild.auth.ldap.followReferrals Boolean LDAP follow referrals enable flag

org.cmdbuild.auth.ldap.search.auth.method String LDAP auth method (none, simple, strong)

org.cmdbuild.auth.ldap.search.auth.password String LDAP auth password

org.cmdbuild.auth.ldap.search.auth.principal String LDAP auth principal

org.cmdbuild.auth.ldap.search.filter String LDAP search filter

org.cmdbuild.auth.ldap.use.ssl Boolean LDAP ssl enable flag

org.cmdbuild.auth.ldap.use.tls Boolean LDAP tls enable flag

CMDBuild – Open Source Configuration and Management Database Page 29

Technical Manual 8. Authentication modes

General configs:

Config Type Description

org.cmdbuild.auth.case.insensitive Boolean Case insensitive login flag

org.cmdbuild.auth.loginAttributeMode String Login attribute mode (username, email,

auto_detect_email)

org.cmdbuild.auth.loginServiceReturnSessionId String Return session id at login (auto, always)

org.cmdbuild.auth.logoutRedirect String Logout redirect URL

org.cmdbuild.auth.maxLoginAttempts.count Integer Max login attempts count

org.cmdbuild.auth.maxLoginAttempts.window Integer Time in seconds between max login attempts

org.cmdbuild.auth.preferredPasswordAlgorythm String Password encryption algorithm (legacy,

cm3easy, cm3)

org.cmdbuild.auth.users.expireInactiveAfterPeriod Iso 8601 Period of time for inactive users expiry

8.3. Configuring LDAP authentication

This section documents how to configure authentication within CMDBuild via LDAP.

In order to manage the user permissions within CMDBuild is necessary that users that have to

access to CMDBuild they are also present within the webapp.

For example, if a user with LDAP UID j.doe needs accessing CMDBuild as a user of the

"technicians" group, you have to perform these steps:

• user creation in j.doe CMDBuild with a default password (not necessarily that of LDAP)

• creation of the Technical Group and definition of the relevant permits

• adding user to group j.doe Technicians

At this point, when you authenticate j.doe, his credentials will be verified (using the authentication

chain defined in auth.methods) against the LDAP tree.

8.4. Single sign on configuration through CAS

This section documents how to configure the single sign on (SSO) within CMDBuild via CAS.

The authentication runs as follows:

• the user asks for the CMDBuild url

• the CAS authenticator sends the request to the CAS server (${cas.server.url} + $

{cas.login.page}) specifying the CMDBuild access url (in the ${cas.service.param}

paramter)

• the CAS server answers with a ticket (${cas.ticket.param} paramter) which you can extract

the username from

• if the username is properly validated/extracted, then CMDBuild gets on with the login

In order to manage the user permissions within CMDBuild is necessary that users that have to

access to CMDBuild they are also present within the webapp.

CMDBuild – Open Source Configuration and Management Database Page 30

Technical Manual 9. Mobile interface activation

9. Mobile interface activation

9.1. Introduction

CMDBuild “mobile” is an interface that can be used on smartphones and tablets in order to run

useful application features during the activities on field.

It is created with “Sencha Touch” (a Javascript framework developed by Sencha, the same

productor of Ext JS framework used by the CMDBuild desktop interface), and it is able to interact

with CMDBuild via REST webservice.

CMDBuild mobile implements the main features of the desktop interface: multilingual, multi group

9.2. Components and architecture

The application is created with the usage of the following components:

• Sencha Touch (Javascript framework created by Sencha)

• Cordova (mobile cross-platform framework)

• Deft JS (mobile enterprise extension for applications developed with Sencha Touch)

• log4javascript (javascript logging framework)

• Crosswalk (tool for the application deployment on a custom webview independent from the

android version)

• Siesta (library for the usage of unit/integration tests)

On the server side, the REST web service layer is developed using the Apache CXF framework,

that is already integrated in CMDBuild, also used for the SOAP web service layer.

The system retraces the software architecture of the REST web service with the following features:

• features divided in web resources

• addressable resources (URI)

• HTTP standard methods (GET, POST, PUT, DELETE)

• JSON media type

• link for the resource navigation

• stateless

9.3. Compatibility

The mobile system is compatible with:

• Android 4.0.3 or more recent

• IOS 6 or more recent

CMDBuild – Open Source Configuration and Management Database Page 31

Technical Manual 9. Mobile interface activation

9.4. Limitation of use

The mobile interface is available only with the non-open source license, which allows only those

who have signed with Tecnoteca srl a maintenance service for the CMDBuild application, and only

until the maintenance is active, with a limited additional charge.

CMDBuild – Open Source Configuration and Management Database Page 32

Technical Manual 10. GUI Framework activation

10. GUI Framework activation

10.1. Introduction

The GUI Framework makes available a simplified interface to non-technical staff.

The GUI Framework includes the following main features:

• it can be activated in portals based on different technologies as it is developed in

javascript / JQuery environment

• it allows an (almost) unlimited freedom when projecting the graphic layout, defined through

an XML descriptor and with the possibility of intervening on the CSS

• it grants a quick configuration thanks to predefined functions (communication,

authentication logics, etc.) and to native graphic solutions (forms, grids, upload buttons and

other widgets)

• it interacts with CMDBuild through the REST webservice

• it is able to gather data from the database of other applications, allowing the management

of mix solutions

10.2. Configuration

The framework defines HTML pages starting from their definition in XML.

Such pages can be inserted into a HTML file, allowing the framework to insert into existing portals

access points to CMDBuild data.

The system configurability can be achieved through the definition of custom CSS and Javascript.

The element that should be inserted into the portal html is a html container (DIV, IFRAME ...) in the

following format:

script>

framework/api/cmdbuildAP.js"></script>

$( document ).ready(function(){

$("#cmdbuilForm").cmdbuildAP({

apiUrl : 'http://10.0.0.107:8080/cmdbuild/services/rest/',

appRootUrl :

'http://10.0.0.107:8080/cmdbuild-gui-framework/api/',

appConfigUrl :

'http://10.0.0.107:8080/cbap/cbap/config/bologna/',

cqlUrl : 'http://10.0.0.107:8080/cbap/cbap/cql/',

customjs : [

'backend/GUIForm.js',

'backend/Process.js'

start: "home.xml",

theme: [

"jquery-ui.theme-crt-toscana.min.css",

"custom.css"

CMDBuild – Open Source Configuration and Management Database Page 33

Technical Manual 10. GUI Framework activation

});

</script>

The style configuration is designated to CSS, which can directly uploaded from the Html tag. This

makes the GUI flexible, allowing the programmer to include it into the portal so that is does not look

like an unrelated element.

You can also define the servers that contain the CMDBuild system, the form configuration files and

the Cql engine, the native data query language in CMDBuild.

In the tag customjs some GUI customization files are inserted.

The tag uploads the GUI engine configuring it with the above-mentioned files.

The forms are defined in XML through a language that is similar to HTML, with the possibility of

defining data management forms directly linked to metadata defined in CMDBuild.

All GUI tags, commands and behaviours can be configured again by the programmer according to

the system criteria.

Since the library refers to JQuery, where the GUI Framework was developed, the programmer can

natively use every plugin compatible with JQuery, developing the available features.

Another element that marks the GUI operation is the "backend" mechanism, i.e. the Javascript

classes that link the GUI to the servers. In this way the application provides further freedom

provided by the possibility to define the data format the server is waiting for and the name of the

server you want to link to.

CMDBuild – Open Source Configuration and Management Database Page 34

Technical Manual 11. GeoServer

11. GeoServer

11.1. Geo Server introduction

CMDBuild includes the ability to manage the geo-reference of assets or of any other information

entities (such as customers, suppliers, locations, etc.) through the visualization on a map and/or

floor plans.

The geo-reference on the territory is made by integration external services such as

“OpenStreetMap”, Google maps, and more, while the management of plans has been implemented

by using the GeoServer open source system.

Through the use of GeoServer you can add custom layers (e.g. plans) that you can use in the GIS

module.

Supported formats are Shape, GeoTiff and WorldImage

11.2. Installing Geo Server

In order to install Geo Server it is necessary to:

• Download the application from the GeoServer official website: http://geoserver.org/

• Deploy the war file in your tomcat installation folder under webapp

• Log in to GeoServer with username admin and password geoserver

• Delete any previously installed workspace

• Create a new workspace with an arbitrary name (I.E. “cmdbuild”)

In order to print the maps from CMDBuild, an additional plugin has to be installed, the plugin can

be downloaded from https://docs.geoserver.org/maintain/en/user/extensions/printing/index.html

To setup the plugin the procedure is the following:

• Download the library geoserver-2.x.x-printing-plugin.zip

• Extract the file and copy the jar files in the geoserver webapp folder under the tomcat

installation folder ( <tomcat_installation_folder>/webapps/geoserver/WEB-INF/lib/ )

• After restarting Tomcat, a “printing” folder will be created in the data folder under the

geoserver webapp

• Add the file named “config.yaml” in the printing folder, this file can be found in the extras

folder inside the package cmdbuild.zip available on the website www.cmdbuild.org

• If any additional information are required, see the official printing informations at:

http://docs.geoserver.org/maintain/en/user/extensions/printing/configuration.html

11.3. Configuring GeoServer in CMDBuild

After logging into CMDBuild and going to the Administration Module, the GIS module can be

enabled under the relative page in the System Config section.

To change the configuration of the GIS Service various tabs are provided to change the geoserver

layers and their order.

CMDBuild – Open Source Configuration and Management Database Page 35

Technical Manual 12. BIM

12. BIM

12.1. Introduction

CMDBuild offers the possibility of visualizing BIM models and connect cards and bim objects.

In previous version CMDBuild made this possible with the usage of BIMServer a service that

stored and provided different APIs to visualize BIM data through ifc files.

From version 3.4 a new BIM viewer has been introduced, the opensource Xeokit.

More information in the following chapters.

12.2. BIMServer introduction

BIMServer is an opensource software made to easily build bim related tools. In order to use ifc files

in CMDBuild, BIMServer has to be installed.

12.3. Installation

CMDBuild supports the version 1.5.138 of BIMServer, this can be obtained on the official GitHub of

BIMServer at the following link: https://github.com/opensourceBIM/BIMserver/releases .

After obtaining the file we can start with the installation procedure:

BIM server is a web application, you can create a new folder called "bimserver" in your local

apache tomcat installation under the webapps folder.

Now extract the war file in the newly created folder.

You can launch tomcat and take a look at the logs in the file "catalina.out", there the initial setup of

BIMServer will be displayed.

Once the app is running proceed to the address http://localhost:8080/BIMServer/ on any browser

to reach the configuration page for BIMServer:

Leave the Site address as it is and choose your server name and description.

CMDBuild – Open Source Configuration and Management Database Page 36

Technical Manual 12. BIM

After pressing next we'll be required to decide the administrator username and password, type

your preferred once, the username has to be an email address.

In the next step we have the possibility of setting up an email, step that isn't mandatory and won't

be done here

In the next page a list of standard plugins will be provided, this plugins will be installed for an

optimal setup of BIMServer, click next.

In the last page by pressing "Setup" the full installation and setup of BIMServer will start, both the

page and catalina.out log will tell us the stage of the installation and when it is completed.

Once the setup is finished you can refresh the page to obtain a status page of your BIMServer:

CMDBuild – Open Source Configuration and Management Database Page 37

Technical Manual 12. BIM

All you need to do to complete the setup of the BIM service is to go in the administration module of

CMDBuild and enable the BIM services with the information you provided during the BIMServer

setup.

12.4. Xeokit introduction

Xeokit is an open source 3D graphics SDK for BIM and AEC. It utilizes a binary model format that

compared to the ifc counterpart is extreamly lightweight (speaking of file size the ratio is around

10:1).

The xeokit viewer has been introduced inside the CMDBuild code as an alternative to BIMServer.

A procedure to migrate ifc files to Xeokit xkt files has also been included.

If there is the need to migrate bim projects to the new file format in the bim project list in

administration a button will perform the automatic conversion from ifc to xkt, and will keep stored

on the database both the ifc and xkt file.

Once all files have been migrated, bimserver can be decommissioned.

When the xeokit viewer is in use, users won’t see any differences in the usage because they will

still upload the ifc file, CMDBuild internally will convert the ifc file to xkt and keep both versions

inside the database.

CMDBuild – Open Source Configuration and Management Database Page 38

Technical Manual 12. BIM

General configs:

Config Type Description

org.cmdbuild.bim.enabled Boolean Bim service enable flag

org.cmdbuild.bim.viewer String Bim service viewer (bimserver or xeokit)

org.cmdbuild.bim.conversiontimeout Integer Conversion timeout for ifc→xkt file

conversion

Bimserver related configs:

Config Type Description

org.cmdbuild.bim.bimserver.enabled Boolean Bim server enable flag

org.cmdbuild.bim.bimserver.url String Bim server URL

org.cmdbuild.bim.bimserver.username String Bim server username

org.cmdbuild.bim.bimserver.password String Bim server password

CMDBuild – Open Source Configuration and Management Database Page 39

Technical Manual 13. CMDBuild configuration in cluster mode

13. CMDBuild configuration in cluster mode

13.1. Cluster introduction

CMDBuild allows you to configure an architecture in Cluster mode, where a webserver load

balancer is activated. This balancer distributes the requests to CMDBuild on various instances of

the application (nodes), connected through the same database PostgreSQL, which is configured in

replication mode Master-Slave.

The service clustering allows you to achieve to goals:

• High Availability: if a CMDBuild instance stops working, other instances can keep the

service on

• Scalability: the availability of various instances (nodes) allows to share the charge and

so to meet quicklier the requests.

The following schema describes the CMDBuild architecture in Cluster configuration:

In the example above the load balancer has been made by the Apache webserver.

Both load balacer and PostgreSQL database can be redundant through different techniques, which

are not considered in this chapter.

CMDBuild – Open Source Configuration and Management Database Page 40

Technical Manual 13. CMDBuild configuration in cluster mode

13.2. Cluster configuration

In this chapter we will simulate the creation of a CMDBuild architecture in Cluster mode, composed

by four servers:

• One server with PostgreSQL as the master database

• One server with an instance of CMDBuild (Node 1) with address 10.0.0.100:8080

• One server with an instance of CMDBuild (Node 2) with address 10.0.0.101:8080

• One server with Apache as the Load Balancer

Below, the path of the webapp cmdbuild within the servers will be identified with $

{cmdbuild_home}.

The folder including the configuration files ${cmdbuild_home}/WEB-INF/conf has to be

synchronized between the various Tomcat Instances: in case the Tomcat instances are located in

different servers, you are suggested to load the folder conf onto the various instances through

NFS, so that you do not have to manage the alignment of several configuration files.

Assuming that CMDBuild has been installed on the two servers by following the installation guide

we can now proceed with the following steps:

Step 1:

The configuration of cmdbuild of both servers has to be changed to tell the application to enable

the cluster mode.

The clustered variable has to be set to true:

org.cmdbuild.cluster.enabled true

This can be performed via rest command, by editing the variable with a setconfig command or by

visualizing the entire configuration with the command editconfig.

Step 2:

Now the service which mantains the communication among the various instances (JGroups) has to

be configured.

The configuration of the communication among the instances described in this manual is based on

a stack of standard protocols. TCP is the transmission protocol it uses.

The configuration that is described below allows the discovery among instances which can be

reached through an IP address or domain name, and should cover the majority of installation

types.

If the objective is to start multiple nodes on the same host than the configuration for the tcp port

has to be changed on one of the nodes with the following configuration:

org.cmdbuild.cluster.node.tcp.port

Now the list of the nodes has to be set via:

org.cmdbuild.cluster.nodes = 10.0.0.101,10.0.0.102

CMDBuild – Open Source Configuration and Management Database Page 41

Technical Manual 13. CMDBuild configuration in cluster mode

13.3. Configuring the load balancer on Apache

Before configuring the load balancer make sure that all the following Apache modules are

functional:

• proxy

• proxy_http

• proxy_balancer

• lbmethod_byrequests

• headers

Then the configuration file of the load balancer module has to be modified.

It is also necessary to configure the desired VirtualHost by activating it in the sites-enabled to setup

a domain to access the cluster.

13.4. Check if the Cluster is working

In order to verify that the clustering is working as intended you can control the table content:

quarz_scheduler_state

which has to be present in the schema quarz in the CMDBuild database.

If everything is working properly for every configured Tomcat node (in our case Node1 and Node2)

a record will appear in the table and the value of the column last_checkin_time will be updated in a

few seconds.

13.5. Applying patches in Cluster mode

If CMDBuild is configured in Cluster mode and the web application has to be updated, the following

procedure has to be followed:

• After shutting down CMDBuild update every single CMDBuild webapp

• Start a single instance

• Reach the started instance via browser and apply any sql patches

• Start the other instances of the cluster

CMDBuild – Open Source Configuration and Management Database Page 42

Technical Manual 14. Appendix: Glossary

14. Appendix: Glossary

ATTACHMENT

An attachment is a file associated to a card.

In order to manage the attachments, CMDBuild uses in embedded mode any document system

which is compatible with the standard protocol CMIS.

The management of the attachments supports the versioning of those files that have been uploaded

a few times, with automatic numbering.