Technical Manual: January 2012 Author Tecnoteca SRL

Version
1.5
Technical Manual
January 2012
Author Tecnoteca srl
www.tecnoteca.com
ENG
www.cmdbuild.org
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, JasperReports, IReport, Enhydra Shark, TWE, OCS
Inventory, Liferay, Alfresco, GeoServer, OpenLayers, Prefuse
We are thankful for the great contributions that led to the creation of these products.
CMDBuild is a project of Tecnoteca Srl. Tecnoteca is

responsible of software design and development, it's the official
maintainer and has registered the CMDBuild logo.
In the project was also involved the Municipality of Udine as the

initial customer.
CMDBuild is released under GPL license (www.gnu.org / copyleft / gpl.html)
CMDBuild is a registered trademark of Tecnoteca Srl.

Everytime 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
Introduction...................................................................................................................................... 4
CMDBuild modules...................................................................................................................................... 4
System configuration........................................................................................................................ 6
Hardware requirements............................................................................................................................... 6
Software requirements................................................................................................................................. 6
Client requirements...................................................................................................................................... 8
Installing CMDBuild using graphical interface ..................................................................................9
Getting started............................................................................................................................................. 9
CMDBuild installation................................................................................................................................... 9
CMDBuild configuration............................................................................................................................... 9
Installing CMDBuild in manual mode..............................................................................................12
Getting started........................................................................................................................................... 12
Database installation................................................................................................................................. 12
Application configuration............................................................................................................................ 13
Configuration of the interface between CMDBuild and Shark....................................................................13
Configuration of the interface between CMDBuild and Alfresco................................................................14
Installing Alfresco DMS.................................................................................................................. 15
Basic configuration.................................................................................................................................... 15
Additional configurations............................................................................................................................ 17
LDAP Authentication...................................................................................................................... 18
Introduction................................................................................................................................................ 18
Configuring authentication type................................................................................................................. 18
Configuring Authentication Header............................................................................................................ 19
Configuring LDAP authentication............................................................................................................... 19
Configuring LDAP authentication....................................................................................................21
Introduction................................................................................................................................................ 21
Installing Liferay portlet.............................................................................................................................. 21
CMDBuild configuration............................................................................................................................. 22
GeoServer...................................................................................................................................... 24
Introduction................................................................................................................................................ 24
Installing Geoserver................................................................................................................................... 24
CMDBuild configuration............................................................................................................................. 24
OCS Inventory Connector..............................................................................................................25
Generality.................................................................................................................................................. 25
Example configuration............................................................................................................................... 25
Application architecture..................................................................................................................26
Database design details................................................................................................................. 27
Design Criteria........................................................................................................................................... 27
Inheritance................................................................................................................................................. 27
Primitive superclasses: "Class" and "Map"................................................................................................ 29
Metadata.................................................................................................................................................... 30
APPENDIX: Glossary..................................................................................................................... 33

Technical Manual
Introduction
CMDBuild is an Open Source web application to model and manage assets and services
controlled by the ICT Department and handle related workflow operations according to ITIL best
practices.
Managing a Configuration Database (CMDB) means keeping up-to-date and available to other
processes the database of components used, their relations and their changes over time.
CMDBuild provides complete support for ITIL best practices; ITIL has become a "standard de
facto", it's a non-proprietary system for services management with a process-oriented criteria.
With CMDBuild, the system administrator can build and extend its own CMDB (hence the project
name), modeling the CMDB according to the company needs; the administration module allows you to
progressively add new classes of items, new attributes and new relations.
In addition, thanks to the integrated workflow engine, it's possible to create, using an external
visual editor, new workflow processes and import / execute them inside the CMDBuild application.
The application includes also JasperReports, an open source report engine that allows you to create
reports; it's possible to design (with an external editor), import and run custom reports inside
CMDBuild.
CMDBuild integrates Alfresco, the popular open source document management system. You can
attach documents, pictures and other files and perform full text searches on text-based files.
The application also includes an interface to synchronize data with external data sources
(databases and mail servers); as an example, you can automatically update your hardware
inventory reading data from OCS Inventory - the open source computer inventory and package
deployement system.
Moreover, it's possible to use the GIS feature to geo-reference and display assets on a
geographical map (external map services) and / or an office plan (local GeoServer).
CMDBuild modules
The CMDBuild application includes two main modules:
the Administration Module, used to define the data model and set config options (classes
and relations, users and permissions, reports and workflows, main options and
preferences)
the Management Module, used to manage cards and relations, add attachments, run
workflow processes, execute reports
The Administration Module is available only to the users with the "administrator" role; the
Management Module is used by all the users to view and edit data.
The system includes also two external components:
a daemon to sync data with external databases; useful, for instance, to update assets from
Automatic Inventory Systems
a webservice to interact with CDMBuild using external applications
This guide is intended for software engineers interested in installing the system and to know the
technical implementation of some of its components.

Technical Manual
You can find all the manuals on the official website (http://www.cmdbuild.org):
system overview ("Overview Manual")
system usage (User Manual)
system administration ("Administrator Manual")
workflow configuration ("Workflow Manual")
webservice details and configuration (Webservice Manual)

Technical Manual
System configuration
In order to install the CMDBuild system you can use either one server or more. On these servers
you install the components of the system:
web server
computing components
database
webservice
documents archive
In the following paragraphs we present the software requirements needed by the CMDBuild
system and how to install and configurate its components.
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 in order to avoid unwanted external
accesses (firewall, DMZ) and to deliver good system on-line availability and suitable response
times.
Hardware requirements
For the CMDBuild installation a physical or virtual serveris required, with the following
characteristics:
recent generation CPU
minimum RAM 4 GB; 6 GB RAM if the same server hosts both the instances of production
and test
minimal disk storage 60 GB, unless 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 UPS is employed in order to avoid sudden electric power failures
Software requirements
CMDBuild installation and use require the following software components.
1) Operating system
You can use any operating system supporting the software listed below (Linux operating system is
best because CMDBuild is more extensively tested on it).
2) Database
PostgreSQL 8.3 or more recent (best PostgreSQL 9.0).

Technical Manual
Be sure that the support to the language "plpgsql" is on and the database is set to code UTF8.
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/5.5 folder inside the CMDBuild zip file;
the library must be placed in /usr/share/tomcat6/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
the subclasses and for managing the historicizing of data cards.
Web site of reference: http://www.postgresql.org/
3) Servlet Container / Web Server

CMDBuild needs the Jakarta Tomcat 5.5 or more recent (best Tomcat 6.0).
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/
4) Document Management System (DMS) Alfresco

In order to use the function of managing the documents attached to the cards in CMDBuild you
need to install the document management system Alfresco.
Using Alfresco (carried out in an embedded way) is optional and it requires the Community 3.4
version.
Reference website: http://www.alfresco.com/
5) Java Libraries
The Java Libraries are required by Apache Tomcat.
CMDBuild requires JDK 1.6.
Reference website: http://www. oracle.com/
6) 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 JasperReports libraries for the production of reports (http://www.jasperforge.org/)
the library Shark for using the workflow engine Enhydra Shark
(http://www.enhydra.org/workflow/shark)
the webservice available from the DMS Alfresco system in order to use its repository
(http://www.alfresco.com/)
the library Ext JS for the generation of the Ajax user interface (http://extjs.com/)
the library Prefuse for the generation of graphs of the relations in Flash technology
(http://prefuse.org/)

Technical Manual
the server and client components for the publication of georeferenced cartography
(http://geoserver.org/ e http://openlayers.org/)
For designing custom reports you can use the visual editor iReport; it produces its descriptor in
compatible format with the JaspertReports engine (http://jasperforge.org/projects/ireport).
For designing personalized workflows we suggest using the visual editor TWE
(http://www.together.at/prod/workflow/twe) or JPEd (http://www.jped.org). Both produce in output a
XPDL 1.0 file compatible with the Enhydra Shark engine.
For integrating systems of automatic inventory we suggest using the OCS Inventory
(http://www.ocsinventory-ng.org/).
Some functionalities of CMDBuild can be integrated as portlets within systems compatible with
Portal JSR, among them Liferay (http://www.liferay.com/).
All software listed above are released with Open Source licence (the operating system is not
included if you choose to use not the Linux operating system).
Client requirements
CMDBuild is a web-based application, so both modules are available using a standard web
browser.
The CMDBuild user needs only a recent release of a web browser on the client (Mozilla Firefox 3.6
or more recent up to version 7, Microsoft Explorer 7 or more recent up to version 9).
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.

Technical Manual
Installing CMDBuild using graphical interface

Getting started
The installation of CMDBuild requires that you have already installed the basic products needed for
its operation, namely:
PostgreSQL database (it must be started and accessible)
Tomcat application server (not to be started)
the DMS Alfresco (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.
Then you start the PostgreSQL service and possibly (but it is not mandatory) the Alfresco service.
CMDBuild installation
After completion of the operations stated above, the installation and setup the standard CMDBuild
is very simple.
Order to install CMDBuild is sufficient:
downloading from the project site (http://www.cmdbuild.org/download) the compressed file
(ZIP file) corresponding to the last version released
copying the directory CMDBuild-{version}.war (it is in "root" of the ZIP file) in the directory
"webapps" of Tomcat, renaming cmdbuild.war
copying the directory CMDBuild-shark (found in the ZIP file in the directory "extras" of the
ZIP file) in the directory "webapps" of Tomcat
copying additional libraries for the choosen version of Tomcat (located in the directory
"extras / tomcat-libs") in the "lib" directory of Tomcat
Once you do this, and only at this point, it will be necessary to also start the Tomcat application
server.
CMDBuild configuration
The basic configuration is done using a few setup pages that CMDBuild presents automatically at
the first use.
To access the setup pages you need only to connect using your browser at
http://localhost:8080/cmdbuild (the address may vary depending on the Tomcat configuration).
1) Language configuration
If the operations described above were carried out correctly it will appear the screen shown here
below:

Technical Manual
From this screen you can set the language of the system.
Checking the "Show language choice in the login window" a language selection menu will be
presented in the login CMDBuild interface.
Once you made your selection, click Next.
2) Database configuration
In the "Database connection" section you must specify:
the host (host name or IP address) that is hosting the PostgreSQL database (usually
localhost)
the PostgreSQL database port (the default port is 5432)
the username for accessing the database PostgreSQL (for DBA activities)
the password to access the PostgreSQL database (for DBA activities)
In the CMDBuild Database section you must specify:
the type of database to configure CMDBuild, choosing from:
creating an empty database
selecting an existing database compatible with CMDBuild 1.0
creation of a database with test data
the database name

Technical Manual
Selecting the checkbox "Create database user with limited privileges," a new PostgreSQL user is
created with all privileges as DBA, but only on the database that will be used / created in the
CMDBuild instance that you are currently configuring.
3) Configuring access credentials
From this screen you can specify the credentials that the user administrator (superuser) will use to
access CMDBuild (either to the Management Module and to the Administration Module). Clicking
on "Finish" you will be redirected to the interface system login.

Technical Manual
Installing CMDBuild in manual mode

Getting started
Before you begin installing CMDBuild you need to unpack the directory cmdbuild.war.
To do this you must copy it in the webapps directory of Tomcat and wait for the application server
to create the cmdbuild directory.
Verify that in Tomcat is present the JDBC PostgreSQL driver.1
Note: In the following we denote:
{CMDBUILD}, the CMDBuild directory in webapps
{ALFRESCO}, the alfresco directory in webapps
Warning: The following installation involves the creation of a new empty database. If you have a
pre-existing database go directly to "Configure the application" paragraph. If you already have a
CMDBuild database please move to "Application configuration" section.
Database installation
To manually install you must do the following:
using a tool with a graphical interface (for example pgAdmin3, a native PostgreSQL) or
from the command line, create the database by specifying a name, for example cmdbuild:
CREATE DATABASE cmdbuild
WITH OWNER cmdbuilduser
ENCODING = 'UTF8';
access the new database cmdbuild and create the language plpgsql:
CREATE LANGUAGE plpgsql;
to create a database with demo data, run the scripts in alphabetical order that you will find
in the directory {CMDBUILD}/WEB-INF/sql/base_schema, or alternatively the file
{CMDBUILD}/WEB-INF/sql/sample_schemas/demo_schema.sql
execute the following SQL commands to create the "Superuser" user (in the example with
username admin and password admin):
INSERT INTO "User" ("Status", "Username", "IdClass", "Password", "Description") VALUES ('A',
'admin', '"User"', 'DqdKW32Mlms=', 'Administrator');
INSERT INTO "Role" ("Status", "IdClass", "Administrator", "Description") VALUES ('A', '"Role"', true,
'SuperUser');
INSERT INTO "Map_UserRole" ("Status", "IdClass2", "IdClass1", "IdObj2", "IdObj1", "IdDomain")
VALUES ('A', '"Role"'::regclass,'"User"'::regclass, currval('class_seq'), currval('class_seq')-1,
'"Map_UserRole"'::regclass);
At this point you have an empty database compatible with CMDBuild system.
1 The JDBC driver can be downloaded at http://jdbc.postgresql.org/download.html

Technical Manual
Application configuration
You can manually configure the application modifying certain files. If Tomcat was already started,
you need to stop it and enter the directory {CMDBUILD}/WEB-INF/conf.
Then you have to do the following:
file cmdbuild.conf
open it with a text editor
select the default language of the system by modifying the "language" (the values are
IT and EN; selecting "true" the choice "languageprompt" in the login interface you can
select the language)
save and close the file
file database.conf
uncomment the three rows
indicate in "db.url" the name of the database to use
under "db.username" and "db.password" indicate the credentials to access the
database
save and close the file
The installation is now finished, restart Tomcat and login into CMDBuild.
Configuration of the interface between CMDBuild and Shark

The items to be checked are the following:
1) Database address
In the file of the shark webapp META-INF/context.xml you have to configure the address of the
database.
If the database has the default name "cmdbuild" you should replace this line:
url="jdbc:postgresql://localhost/${cmdbuild}"
with
url="jdbc:postgresql://localhost/cmdbuild"
2) URL and ports

Verify that in the Shark.conf file the following parameters are correctly set:
DatabaseManager.ConfigurationDir=${shark_webapp_path}/conf/dods
CMDBuild.WS.ConfigPath=${shark_webapp_path}/conf/axisrepository
CMDBuild.WS.EndPoint=http://${serverip}:${serverport}/$
{cmdbuild_webapp}/services/soap/Webservices
CMDBuild.WS.ExtSync.EndPoint=http://${serverip}:${serverport}/$
{cmdbuild_webapp}/services/soap/ExternalSync

Technical Manual
CMDBuild.EndPoint=http://${serverip}:${serverport}/${cmdbuild_webapp}/shark/
3) Authorizations
From the Administration Module CMDBuild you have to enter the Setup menu and:
enable the workflow (with the appropriate checkbox)
set the URL to which the Shark service responds
4) Starting the service

The Shark Tomcat service must already be active when you start operating across the workflows
using the CMDBuild user interface.
On Windows the path should be expressed with the bar reversed:
DatabaseManager.ConfigurationDir=C:/srv/tomcat/webapps/shark/conf/dods
or double
DatabaseManager.ConfigurationDir=C:\\srv\\tomcat\\webapps\\shark\\conf\\dods
One way to check the proper functioning of the Shark instance is to refer to the its log file.
Configuration of the interface between CMDBuild and Alfresco
1) Configuring the CMDBuild side

To configure the use of Alfresco Community 3.4 with CMDBuild enter the directory {CMDBUILD}/
WEB-INF/conf and open with a text editor the file dms.conf (legacydms.conf for CMDBuild
versions prior to 1.4).
It is then necessary to perform the following operations:
modify the "enabled" from false to true
verify that in "server.url" is inserted the url from which Alfresco can be reached
edit fileserver.port inserting the port number on which the Alfresco FTP service is running
(see next paragraph)
edit the entry "repository.fspath" with the path of the space of CMDBuild on Alfresco,
similar to the "repository.app"
specify under "category.lookup" the category of CMDBuild used in Alfresco (default
"AlfrescoCategory"
2) Alfresco side configuration

Refer to chapter "Installing Alfresco DMS"

Technical Manual
Installing Alfresco DMS

Note: in the following we denoted {ALFRESCO} the alfresco installation directory (for example
/opt/alfresco).
The release 3.4 of Alfresco uses by default a wizard to simplify installation and configuration of
basic settings. In particular, you have to specify the following:
ports used by Tomcat
port used by the FTP server
settings related to the database (the Alfresco 3.4 uses by default MySQL)
If you decide to proceed using the manual installation you can refer to the following.
Basic configuration
1) Configuring Tomcat
Configure the start of the Tomcat server used by Alfresco on ports different from the Tomcat server
used by CMDBuild.
Go to the directory
{ALFRESCO}/tomcat/conf
Open to edit the server.xml file and change the properties:

<Server port="8005" shutdown="SHUTDOWN">
...
<Connector port="8080" protocol="HTTP/1.1" ... />
...
<Connector port="8009" protocol="AJP/1.3" ... />
so as not to conflict with the instance of Tomcat used by CMDBuild. For example you could use the
following (always taking care to other instances of Tomcat in your system):
<Server port="9005" shutdown="SHUTDOWN">
...
<Connector port="9080" protocol="HTTP/1.1" ... />
...
<Connector port="9009" protocol="AJP/1.3" ... />
2) Configuring the repository and the database

Go to the directory {ALFRESCO}/tomcat/shared/classes/ and edit the file il file alfresco-
global.properties (if not present you may use a copy of the file alfresco-
global.properties.sample). Change the following properties:

Technical Manual
dir.root={REPOSITORY DIRECTORY}
to define the location of the repository where documents are stored (for example
C:/alfresco/repository for Windows systems or /var/alfresco/repository for *nix systems).
Alfresco supports the following databases: HSQL (default), MySQL, Oracle, Sybase, SQLServer,
and PostgreSQL. We suggest addressing Alfresco to a new database managed by the same
PostgreSQL server used for CMDBuild. Since during installation it is not possible to make this
choice, you have to do it manually.
Set the following properties files in the same file alfresco-global.properties:
db.driver=org.postgresql.Driver
db.username=postgres
db.password=postgres
db.url=jdbc:postgresql://localhost:5432/alfresco
Copy the drivers to access the Postgres database (interface library postgresql-8.0-313.jdbc3.jar or
later) in {ALFRESCO}/tomcat/lib.
Using a GUI tool (for example pgAdmin3 of PostgreSQL) or from the command line to create the
database using the name specified in the property "db.url" above referred (in the "alfresco"
example).
Also in the file alfresco-global.properties edit the following lines to enable the ftp server:
ftp.enabled=true
ftp.port=1121
ftp.ipv6.enabled=false
Be careful that if host is already occupied by another FTP server, then you have to change the port
that the FTP server will run Alfresco.
The specified port must be equal to that specified in the file:
{CMDBUILD}\WEB-INF\conf\dms.conf
At the end, once the initial database creation is successful, stop the Alfresco and check if the file
alfresco-global.properties property "db.schema.update" is set to false (or possibly commented
out):
db.schema.update=false
Additional configurations
Create in Alfresco the "space" intended to contain CMDBuild attachments and the category
associated with these documents.
Avviare Alfresco, se non ci sono problemi dopo qualche minuto si potr effettuare l'accesso ad

Technical Manual
Alfresco tramite web browser all'indirizzo:

http://{SERVER}:{PORT}/alfresco
The default credentials are "admin" both as the user name and the password.
In the "Navigator" go to "Company Home", then "User Homes" and create a space with the same
name as that specified in the file:
{CMDBUILD}\WEB-INF\conf\dms.conf (for example "cmdbuild")
Go now in the administration console of Alfresco (first icon on the upper bar), go to "Category
Management" and create a new category with the same name and description as specified in the
file:
{CMDBUILD}\WEB-INF\conf\dms.conf (for example "AlfrescoCategory")
At this point the configuration is complete. When you restart Tomcat, you can also handle
attachments CMDBuild.

Technical Manual
LDAP Authentication
Introduction
With version 1.2.3 is available the option to delegate the authentication to access CMDBuild to an
LDAP server.
This possibility concerns the control of the account (username and password). Profiles and
permissions are still managed within the CMDBuild group to which the user belongs.
The parameters to configure the behavior of CMDBuild when authenticating are indicated in the file
auth.conf in the directory WEB-INF of the CMDBuild webapps within Tomcat.
From this file is possible.
The file is divided into 3 sections:
configuring the type of authentication
configuring header authentication
configuring LDAP authentication
Configuring authentication type

Below are the parameters to be set during configuration and their meaning is specified.
1) auth.methods
With this parameter you can define the authentication "chain" of CMDBuild. It is possible, i.e., to
define in cascade which types of authentication you can use to allow access to the user and set
the priority.
Example
auth.methods=LdapAuthenticator,DBAuthenticator
The configuration in the previous example indicates that whenever a user logs into the system,
CMDBuild must first verify the credentials via LDAP, and if they fail, via the data base in CMDBuild.
The accepted parameters are:
HeaderAuthenticator (authentication via header control)
LdapAuthenticator (authentication via credential verification on LDAP)
DBAuthenticator (standard authentication)
2) serviceusers
With this parameter you can define the service users of CMDBuild. This kind of privileged users is
planned for the exclusive use of external systems such as, for example, Liferay portlet, then the
login interface will be disabled.

Technical Manual
3) force.ws.password.digest
If this parameter is set to "true", it forces the use of specific Username Token with password digest
for authenticating using webservice.
Setting that parameter to "false" you can also use plain text passwords for authentication via
Username Token. This can be useful combined with the use of LDAP for access control within
CMDBuild.
Configuring Authentication Header

From this section you can configure the authentication using the header verification.
To do this simply edit the file header.attribute.name and specify the name of the attribute present
in the HTTP header to be used to authenticate the user on CMDBuild.
This type of authentication requires the presence of an upstream authentication system, which
takes care of generating the specific headers that can then be used to authorize access to
CMDBuild.
Configuring LDAP authentication

This section documents how to configure authentication within CMDBuild via LDAP.
CMDBuild currently supports only authentication "simple bind". However, you can use the
'"anonymous bind" for the user search in the LDAP tree.
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.
Below there is a description of the configuration parameters.
1) ldap.server.address
This attribute is used to specify the address to which you can reach the LDAP server.
Example:
ldap.server.address=localhost
2) ldap.server.port
This attribute is used to specify the port the LDAP server. The default is 389.
Example:
ldap.server.port=389

Technical Manual
3) ldap.use.ssl
It specifies whether to use an encrypted connection to the LDAP server. The default is disabled.
Example:
ldap.use.ssl=true
4) ldap.basedn
This attribute indicates the Base DN that will be used to query the LDAP tree.
Example:
ldap.basedn=dc=example,dc=com
5) ldap.bind.attribute
This attribute indicates the attribute will be run on the bind user.
For example, as an attribute for specifying bind dn uid and considering the basis indicated above,
the LDAP query that will be generated uid = username, dc = example, dc = com.
Example:
ldap.bind.attribute=uid
6) ldap.search.filter
You can specify with this attribute, a search filter to be used for research.

Technical Manual
Configuring LDAP authentication

Introduction
CMDBuild makes available JSR186 portlets through which you can export some of its features in
compatible intranet portals (the CMDBuild portlet is currently certified with the open source Liferay
portal).
JSR168 Portlets are Java web components that can be used as a plug-in within "containers" such
as web portals compatible with this standard. With this mechanism you can configure the portal in
a customized way by placing portlets in the pages of interest and sharing some services of the host
system including the authentication. As in the previous paragraph then CMDBuild portlets
communicate via its webservice.
The CMDBuild portlet makes available some features to non-technical users, because would find
difficult to use the application standard interface.
The portlet includes the following functions:
management of a data sheet (insert, modify, delete)
initiation and progress of a process
running a report
The configuration includes two aspects:
configuration of CMDBuild portlets in Liferay
configuration of CMDBuild
The portlet CMDBuild includes three different management options:
access only to users registered as system users of CMDBuild
access also to users of "guest" type (i.e. not registered as system users of CMDBuild), but
included in a class "application" CMDBuild configured (e.g. employees, suppliers, etc.)
access also to users of "guest" type (ie not registered CMDBuild System), which are not
even included in a "application" class of CMDBuild (e.g. citizens, students, etc.)
Installing Liferay portlet

The configuration options are stored in two files:
portlet.properties (this file is a "template" and should not be changed)
portlet-ext.properties (overwrites the "template" file, all customizations are to be included in
this file)
The two files are stored in the directory:
WEB-INF/classes
within the portlet webapp.

Technical Manual
The main parameters are:

cmdbuild.url: URL of the CMDBuild webservice(default
http://localhost:8080/cmdbuild/services/soap/Private)
cmdbuild.user: user-id for accessing the webservice (default "portlet")
cmdbuild.password: password for accessing the webservice (default "portlet")
cmdbuild.group: the above user's group membership (default "Guest", you have to create
it in CMDBuild)
user.class: the "application" class of CMDBuild containing the list of users who will have
access to portlets
user.attribute.username: the attribute containing the username, in the class indicated in
the previous step (default "Username")
user.attribute.email: the attribute containing the email address, within the class specified
in the preceding paragraph (default Email)
auth.method: the authentication policy, which may take the value "username" or "email"
(default "email")
Example:
cmdbuild.url=http://localhost:8080/cmdbuild-test/services/soap/Private
user.class=Employee
These values override the default properties with a new URL and a new class name.
Warning
For the changes to the configuration parameters to take effect you have to restart Liferay.
CMDBuild configuration
In the following we will refer with ${CMDBUILD} the directory containing the CMDBuild "webapp"
inside Tomcat.
Webservice user
You have to modify the file ${CMDBUILD}/WEB-INF/conf/auth.conf and change the property
serviceusers in accordance with the value defined for the property cmdbuild.user defined in the
portlet-ext.properties. For the change to take effect you have to restart CMDBuild.
Then, from within the CMDBuild Administration module, you have to:
create a new user (as defined in the cmdbuild.user property of the portlet-ext.properties
file)
create a new group (as defined in the cmdbuild.group property of the portlet-
ext.properties file)
add the new user to the new group

Technical Manual
set the new group as a group "default login" for the new user (required for authentication
type "guest")
create a "custom" menu for the new group (optional)

Technical Manual
GeoServer
Introduction
CMDBuild includes the ability to manage the geo-reference of the assets or of other information
entities (customers, suppliers, locations, etc.) through visualization on maps and/or floor plans.
The geo-reference on the territory is made by integrating external services such as
OpenStreetMap, Google maps, etc., 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
WorldImage.
Installing Geoserver
In order to install Geoserver it is necessary to:
download the application from the official website (http://geoserver.org/)
deploy the war file in Tomcat
log-in using the username admin and password geoserver
delete all preinstalled workspaces
create one workspace called, for example, "cmdbuild"
Configuring CMDBuild
Once you select the Administration Module of CMDBuild, you have to access the GIS page of the
Setup menu and to enable the GIS module.
In order to do so you access the GIS menu and set the following items:
External Services
enable GeoServer
specify the parameters related to the installation
specify the name of the workspace you created earlier
specify the credentials of the administrator
Geoserver layers
add the necessary layers, which are then stored in Geoserver
Layers order
specify the order of layers as will be presented in the Management Module.

Technical Manual
OCS Inventory Connector

Generality
CMDBuild provides the ability to configure the periodic mechanisms to update (e.g. at night) your
database from external data sources.
In particular, this mechanism is used to synchronize the technical data of certain categories of
assets from systems of Automatic Inventory, able to collect this information through software
"agents" installed on the assets that provide for this.
Among these discovery solutions we suggest the OCS Inventory system that includes all the
features you need and it's released under open source license.
The same synchronization system can however be used in other areas, such as the updating of
the company's staff archive or some information about assets of the company.
The mechanism implemented is sufficiently generic and it is based on the following criteria and
requirements:
the external data source is accessible from the CMDBuild server and it is based on one of
the supported databases (currently MySQL, PostgreSQL, Oracle, SQLServer)
the update is done on a periodic basis through a generic daemon that comes with
CMDBuild
the behavior of the daemon is driven by a XML transformation file (XSLT) properly
configured and supported by specific APIs developed within CMDBuild
the daemon must find in the external database "views" appropriate to use as "catalog" of
objects to be queried
multiple daemons can be scheduled simultaneously by using different XSLT files
you have to configure the XSLT file manually
the updating tasks are subject to an approval workflow, you can:
be zero, thus activating your changes with immediate effect
only include a email of notification
require an explicit acceptance that shall guarantee the performance in a controlled manner
perform any type of flow according to the rules laid down in the workflow system
implemented in CMDBuild
Example configuration
For an example of the connector configuration file you can refer to:
http://www.cmdbuild.org/download/download/filesystem/external-connectors-1.3.1.0.zip
downloadable from the project site.

Technical Manual
Application architecture
The CMDBuild software application is structured in layers, each of which communicates only with
the layer immediately above and below.
The full list of layers arranged in the system includes (from top to bottom):
Client module
web client access layer (JSON-RPC)
layer access for other clients (SOAP)
Server Module
"Filter" and "Servlets" layers for decoding the JSON-
RPC requests, serialization of responses and
management aspects of utility (language and
configuration control)
"Axis" layer for managing the SOAP requests
"Operation Layer" for managing the access
privileges to the data
"Object relational mapping" for the instantiation in
Java classes of data and structures corresponding
to the model configured in the database
database data model
layer of stored procedures for implementing the
"logic" part encapsulated in the database
layer of the system views for easy access to some system information (catalog classes
and attributes, catalog and list domains reports, user permissions, tree menus, etc.)
data tables

Technical Manual
Database design details

Design Criteria
The database design had to respond to a set of basic
requirements:
managing the multi-level hierarchical structure of
classes (superclass / subclass), in order to
specialize a class while maintaining general
attributes in the superclasses
managing relationships "many to many" between
classes
tracing the complete history of data changes
over time and relationships
For all three requirements have been identified as particularly useful the mechanism of "derivation"
between classes made available by the open source object-relational database PostgreSQL.
It was therefore decided to use PostgreSQL as database support for CMDBuild, thereby designing
in an extremely natural way the structures described above.
Inheritance
1) Multi-level hierarchical structure

Using the keyword "inherits" it is possible to create a table in PostgreSQL that "specializes"
another, adding some specific attributes and finding all the attributes defined in the superclass.
Example:
CREATE TABLE "Asset"
(
"Id" integer NOT NULL DEFAULT nextval('Asset_SEQ'::text),
"Code" varchar(100),
"Description" varchar(250),
"SerialNo" varchar(40),
"VersionNo" varchar(32),
"InstallationDate" timestamp,
"WarrantyExpireDate" timestamp,
"State" varchar(16),
"StateDate" timestamp,
CONSTRAINT asset_pkey PRIMARY KEY ("Id")
)

Technical Manual
CREATE TABLE "Monitor"

(
"MonitorType" varchar,
"ScreenSize" varchar(16),
"MaxScreenRes" varchar(16)
) inherits ("Asset")
2) "Many to many" relations

The different types of relationships between classes are implemented, each with a specific
relationship table "many to many", created by derivation from a superclass defined by default in
order to simplify the creation of subclasses and to ensure the structural homogeneity.
Example:
CREATE TABLE "Map"
(
"Id" integer NOT NULL DEFAULT nextval('Map_SEQ'::text),
"IdDomain" regclass,
"IdClass1" regclass,
"IdObj1" integer NOT NULL,
"IdClass2" regclass,
"IdObj2" integer NOT NULL,
"Status" character(1),
"User" character varying(40),
"BeginDate" timestamp without time zone NOT NULL DEFAULT now(),
"EndDate" timestamp without time zone,
CONSTRAINT map_pkey PRIMARY KEY ("Id")
)
CREATE TABLE " Map_aggregazione"

(
) inherits ("Map")
3) Change history
The derivation mechanism of the classes in PostgreSQL is used also for the management of the
history of changes. In order to achieve this, we create a derived class for each type of object, in
which through special triggers the current record is stored in the database before changing its
attributes, associating the "Id" of the record, the modification date and the login of the operator who
made the change.
Example:
CREATE TABLE "Monitor"

Technical Manual
(
"MonitorType" varchar,
"ScreenSize" varchar(16),
"MaxScreenRes" varchar(16)
) inherits ("Asset")
CREATE TABLE "Monitor_history"

(
"CurrentId" integer NOT NULL,
"EndDate" timestamp NOT NULL DEFAULT now()
) inherits ("Monitor")
Through the same mechanism we handle the story of changes in relationships, that is, by creating
a derived class for each type of relationship, in which through special database triggers records are
stored before deleting the current relationship. This is done by attaching the "Id" of the record, the
modification date and the login of the operator who made the change.
Primitive superclasses: "Class" and "Map"

On the basis of the philosophy described above we defined two system superclasses called
respectively:
"Class," which is the generic data class from which to derive the specific cards of the
different data models
"Map", which is the generic table of relationships between pairs of classes
The meaning of the attributes of both superclasses is described in the following table:
"Class" Superclass
Name SQL Type Description
Id integer table primary key
IdClass regclass Table OID
BeginDate timestamp insertion date
User varchar(40) the user who inserted the record
Status character(1) logical state of the record (A = active, deleted = N,
U = updated)
Code varchar(100) data field: it can be used to store the identifier of a
record (e.g. the serialnumber of a computer)
the "Code" field can be renamed (e.g. "VATCode"
in a class containing customers or suppliers) or it
can be disabled.
Description varchar(250) data field: is the description of the record
in CMDBuild it is very important because the value
is shown in the selection lists for the enhancement

Technical Manual
of the attributes of type "reference" (foreign keys of

other classes)
Notes text free notes
"Map" Superclass
Name SQL Type Description
IdDomain regclass Table OID
IdClass1 regclass OID of the first class
idObj1 integer index of the object in relation for the first class
IdClass2 regclass OID of the second class
idObj2 integer index of the object in relation for the second class
User varchar(40) the user who inserted the record
Status character(1) logical state of the record (A = active, deleted = N,
U = updated)
BeginDate timestamp insertion date
EndDate timestamp insertion date
All the tables defined in the CMDBuild application inherit from the "Class" table. This table add
specific descriptive fields to the information the tables represent.
Derived tables can be "Super Class" or normal "Class". Only the latter contain data, the first are
used as a logical grouping of classes useful for defining attributes common to multiple classes and
domains in a more general way.
Each normal class in the database is accompanied by a further table, dedicated to the changed
data history, whose name is the same but completed with the suffix "_history". The "historical"
tables inherit from the tables and share all the fields with the tables from which they derive,
completed only with the link to the active data card and with the link to the expiry date.
Each time a record of the main table undergoes a change or cancellation the original record is
moved to the history table. During this operation the values of the column "Status" (according to
the table above) and of the column "EndDate" (with the timestamp of the transaction) are updated.
Similarly, all domains between Classes or Super Classes inherit from the "Map" Table and each
inherited domain holds the corresponding table for versioning (with the same suffix "_history").
By convention all domains have the prefix "Map_".
Metadata
To define the data model CMDBuild uses a set of metadata, associated to the tables and their
attributes which extend the basic metadata managed by PostgreSQL.
For storing such metadata the comments associated with tables and columns are used. They are
stored in the system table "pg_description".
The metadata structure follows a strict and forced syntax, structured according to a key / value that
follows the syntax defined by the following regular expression:
(([A-Z0-9]+): ([#A-Za-z0&-9_\-\:\s]*)|+)*

Technical Manual
For example, a comment can be:

MODE: read|DESCR: some text
The valid comments related to a class as a whole are:
Metadata for class definition
Key Meaning Possible values Notes
MODE access modes reserved|read|write mandatory
TYPE table type class|domain mandatory
SUPERCLASS indicates whether the true|false default = false
table is a superclass or
not
DESCR description shown to any value mandatory
the user
STATUS status of use of the active|not active mandatory
table
All other keys are ignored by the system that interprets the metadata.
The valid comments related to a attribute are:
Attributes metadata
Key Meaning Possible values Notes
MODE access modes reserved|read|write mandatory
DESCR description shown to any value mandatory
the user on the
management form
(label)
INDEX display order of the a number physical position in
attribute on the the DB, if absent
management form
BASEDSP indicates whether the true|false default = false
attribute is shown in the
"grid" display
GROUP Display "page" of the a string containing
attribute (for paging) the label assigned
to the page
FIELMODE Field display mode write|hidden|read
REFERENCEDOM domain used to set a a valid domain for not mandatory
reference field the class
REFERENCEDIRECT direction of the true|false Mandatory only if you
relationship with valorized
respect to the REFERENCEDOM
corresponding domain
REFERENCETYPE reference type restrict Mandatory only if you
according to delete valorized
operations REFERENCEDOM
LOOKUP lookup list bound to the a lookup list not mandatory

Technical Manual
attribute
STATUS status of use of the active|not active mandatory
table
All other keys are ignored by the system that interprets the metadata.
The users are advised not to intervene manually on such metadata, so as not to cause serious
malfunctions in the CMDBuild mechanisms and consequently in the consistency of the data stored
in the system.

Technical Manual
APPENDIX: Glossary
ATTACHMENT
An attachment is a file associated to a card. Attachments containing text (PDF, Open Office,
Microsoft Word, etc.) are indexed in full text mode so they can appear in search results.
WORKFLOW STEP
Activity: a workflow step A step has a name, an executor, a type, attributes - if any and methods
with statements (CMDBuild API) to be executed. A process instance is a single process that's been
automatically activated by the application or manually activated by an operator.
See also: Process
ATTRIBUTE
The term refers to an attribute of a CMDBuild class. CMDBuild allows you to create new attributes
(in classes and domains) or edit existing ones. For example, in "supplier" class the attributes are:
name, address, phone number, etc.. Each attribute corresponds, in the Management Module, to a
form field and to a column in the database.
See also: Class, Superclass, Attribute type
CI
We define CI (Configuration Item) each item that provides IT service to the user and has a
sufficient detail level for its technical management. CI examples include: server, workstation,
software, operating system, printer, etc. operating, printer, ecc
See also: Configuration
CLASS
A Class is a complex data type having a set of attributes that together describe that kind of data. A
Class models an object that has to be managed in the CMDB, such as a computer, a software, a
service provider, etc. CMDBuild allows the administrator - with the Administration Module - to
define new classes or delete / edit existing ones. Classes are represented by cards and, in the
database, by tables automatically created at definition time.
See also: Card, Attribute
CONFIGURATION
The configuration management process is designed to keep updated and available to other
processes the items (CI) informations, their relations and their history. It's one of the major ITIL
processes managed by the application.
See also: CI, ITIL
DATABASE
The term refers to a structured collection of informations, hosted on a server, as well as utility

Technical Manual
softwares that handle these informations for tasks such as initialization, allocation, optimization,
backup, etc.. CMDBuild relies on PostgreSQL, the most powerful, reliable, professional and open
source database , and uses its advanced features and object oriented structure.
DOMAIN
A domain is a relation between two classes. A domain has a name, two descriptions (direct and
inverse), classes codes and cardinality. The system administrator, using the Administration
Module, is able to define new domains or delete / edit existing ones.
See also: Class, Relation
GIS
A GIS is a system able to produce, manage and analyze spatial data by associating geographic
elements to one or more alphanumeric descriptions. CMDBuild GIS capabilities allow you to create
geometric attributes (in addition to standard attributes) that represent, on plans / maps, markers
position (assets), polylines (cable lines) and polygons (floors, rooms, etc.).
ITIL
"Best practices" system that established a "standard de facto"; it's a nonproprietary system for the
management of IT services, following a process-oriented schema (Information Technology
Infrastructure Library). ITIL processes include: Service Support, Incident Management, Problem
Management, Change Management, Configuration Management and Release Management. For
each process, ITIL handles description, basic components, criteria and tools for quality
management, roles and responsibilities of the resources involved, integration points with other
processes (to avoid duplications and inefficiencies).
See also: Configuration
LOOKUP
The term "Lookup" refers to a pair of values (Code, Description) set by the administrator in the
Administration Module. These values are used to bind the user's choice (at form filling time) to one
of the preset values. With the Administration Module it's possible to define new "LookUp" tables
according to organization needs.
PROCESS
The term "process" refers to a sequence of steps that realize an action. Each process will take
place on specific assets and will be performed by specific users. A process is activated by starting
a new process (filling related form) and ends when the last workflow step is executed.
See also: Worflow step
RELATION
A relation is a link between two CMDBuild cards or, in other words, an instance of a given domain.
A relation is defined by a pair of unique card identifiers and a domain. CMDBuild allows users,
through the Management Module, to define new relations between cards stored in the database.
See also: Class, Domain

Technical Manual
REPORT
The term refers to a document (PDF or CSV) containing informations extracted from one or more
classes and related domains. CMDBuild users run reports by using the Management Module;
reports definitions are stored in the database.
See also: Class, Domain, Database
CARD
The term "card" refers to an element stored in a class. A card is defined by a set of values , ie the
attributes defined for its class. CMDBuild users, through the Management Module, are able to store
new cards and update / delete existing ones. Card informations are stored in the database and,
more exactly, in the table/columns created for that class (Administration Module).
See also: Class, Attribute
SUPERCLASS
A superclass is an abstract class used to define attributes shared between classes. From the
abstract class is then possible to derive real classes that contain data and include both, shared
attributes (specified in the superclass) and specific subclass attributes. For example, you can
define the superclass "Computer" with some basic attributes (RAM, HD, etc.) and then define
derived subclasses "Desktop", "Notebook", "Server", each one with some specific attributes.
See also: Class, Attribute
ATTRIBUTE TYPE
Each attribute has a data type that represents attribute information and management.
The attribute type is defined using the Administration Module and can be modified within some
limitations, depending on data already stored in the system.
CMDBuild manages the following attribute types: "Boolean", "Date", "Decimal", "Double", "Inet" (IP
address), "Integer", "Lookup" (lists set in "Settings" / "LookUp"), "Reference" (foreign key), "String",
"Text", "Timestamp".
See also: Attribute
WEBSERVICE
A webservice is an interface that describes a collection of methods, available over a network, and
works using XML messages.
With webservices, an application allows other applications to interact with its methods.
WIDGET
A widget is a component of a GUI that improves user interaction with the application.
CMDBuild uses widgets (presented as "buttons") that can be placed on cards or processes. The
buttons open popup windows that allow you to insert additional information, and then display the
output of the selected function.

Technical Manual: January 2012 Author Tecnoteca SRL

Uploaded by

Copyright:

Available Formats

Technical Manual: January 2012 Author Tecnoteca SRL

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Technical Manual: January 2012 Author Tecnoteca SRL

Uploaded by

Copyright:

Available Formats

Version

CMDBuild is a project of Tecnoteca Srl. Tecnoteca is

In the project was also involved the Municipality of Udine as the

CMDBuild is released under GPL license (www.gnu.org / copyleft / gpl.html)

CMDBuild is a registered trademark of Tecnoteca Srl.

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

CMDBuild Open Source Configuration and Management Database Page 2

CMDBuild Open Source Configuration and Management Database Page 3

CMDBuild Open Source Configuration and Management Database Page 4

CMDBuild Open Source Configuration and Management Database Page 5

CMDBuild Open Source Configuration and Management Database Page 6

3) Servlet Container / Web Server

4) Document Management System (DMS) Alfresco

6) Libraries included in the release

CMDBuild Open Source Configuration and Management Database Page 7

CMDBuild Open Source Configuration and Management Database Page 8

Installing CMDBuild using graphical interface

CMDBuild Open Source Configuration and Management Database Page 9

CMDBuild Open Source Configuration and Management Database Page 10

3) Configuring access credentials

CMDBuild Open Source Configuration and Management Database Page 11

Installing CMDBuild in manual mode

1 The JDBC driver can be downloaded at http://jdbc.postgresql.org/download.html

CMDBuild Open Source Configuration and Management Database Page 12

Configuration of the interface between CMDBuild and Shark

2) URL and ports

CMDBuild Open Source Configuration and Management Database Page 13

4) Starting the service

Configuration of the interface between CMDBuild and Alfresco

1) Configuring the CMDBuild side

2) Alfresco side configuration

CMDBuild Open Source Configuration and Management Database Page 14

Installing Alfresco DMS

Open to edit the server.xml file and change the properties:

2) Configuring the repository and the database

CMDBuild Open Source Configuration and Management Database Page 15

CMDBuild Open Source Configuration and Management Database Page 16

Alfresco tramite web browser all'indirizzo:

CMDBuild Open Source Configuration and Management Database Page 17

Configuring authentication type

CMDBuild Open Source Configuration and Management Database Page 18

Configuring Authentication Header

Configuring LDAP authentication

CMDBuild Open Source Configuration and Management Database Page 19

CMDBuild Open Source Configuration and Management Database Page 20

Configuring LDAP authentication

Installing Liferay portlet

CMDBuild Open Source Configuration and Management Database Page 21

The main parameters are:

CMDBuild Open Source Configuration and Management Database Page 22

CMDBuild Open Source Configuration and Management Database Page 23

CMDBuild Open Source Configuration and Management Database Page 24

OCS Inventory Connector

CMDBuild Open Source Configuration and Management Database Page 25

CMDBuild Open Source Configuration and Management Database Page 26

Database design details

1) Multi-level hierarchical structure

CMDBuild Open Source Configuration and Management Database Page 27

CREATE TABLE "Monitor"