Openbravo Technical Training 2

Chapter 3 - Modularity & Initial Client Setup

v3.1.4
2008-2014 Openbravo S.L.U. All rights reserved. The information in this document is confidential
and may not be disseminated or disclosed to third parties (either in digital form or on paper) without the prior written
consent of Openbravo S.L.U.

Introduction
Modularity
Installing Modules Using the Module Management Console
Installing Modules Using the Source Control
Rebuilding the Application
Creating Project's Module Structure
Creating a New Module
Dependencies
DB Prefix
Data Package
Creating a Template
Dependencies
Exporting New Structures
Initial Client Setup
Initial Organization Setup
Additional Roles

Introduction
This chapter will guide the student through some basic steps and setups required before development can
commence, in particular creating modules and the a fresh client.

Modularity
Modularity is an important feature of the Openbravo ERP Platform, making the system very flexible,
modular and maintainable. Introduced in version 2.50, modularity is a new approach to development,
packaging and distribution of customizations done to the application. Before any changes are made
or any additional functionalities developed, a module must be created to which these will belong. An
additional benefit to this concept is that the developer is able to neatly package all developments into a
single .obx file that is easy to publish and share.
Modules can also contain artifacts required for setting up new clients/customers such as Chart of Accounts,
Tax Configurations, etc. That is why installing the Spain Localization Pack will be a prerequisite for the
Initial Client Setup of our Green Terrace Hotel.
If you are not yet proficient in Openbravo ERP Platform modularity, we recommend the following articles:
http://wiki.openbravo.com/wiki/Modularity
http://wiki.openbravo.com/wiki/Modularity_Concepts

Installing Modules Using the Module Management Console

1

One of the major advantages of modularity is the fact that modules are now much easier to publish and
share. Consequently, everyone can benefit from each other's work.
For the purpose of this course and the Hotel Management Scenario we will install and use the Localization
Pack Spain. Using the System Administrator role, navigate to General Setup || Application || Module
Management and click on the [Add Modules] tab. Then, find the Localization Pack Spain by browsing the
list or using the provided search:

Click the Install Now button next to it and click through the wizard to complete the installation. Do not
rebuild yet!

Installing Modules Using the Source Control

Now, let's see how modules can also be installed through the file system, using Openbravo's code
repository to obtain the sources of the Openbravo HQL Query Tool module.
Execute the following command inside the openbravoadt/modules folder:
hg clone https://code.openbravo.com/erp/mods/org.openbravo.utility.hqlquerytool

This will checkout the latest sources of the Openbravo HQL Query tool into the modules/
org.openbravo.utility.hqlquerytool folder. This action is actually identical to installing a module
through the module management console but this way, you have the full module's repository available
locally.
Note 1: This method of installing modules should be used when installing modules that you will be
developing. In such a case, one needs to commit and push changes to the server so having a checkout of
a module is a must.
Note 2: Checking out a single module or simply putting one module's sources inside the modules/ folder
does not take care of the dependencies (if any)! If that module depends on other modules, it is the
developer's responsibility to checkout sources of those modules as well!
Note 3: You can find other publicly accessible modules on https://code.openbravo.com/erp/mods/.

Rebuilding the Application

2

You are probably familiar with using the Module Management screen to install modules and rebuild the
application. For example, after installing one or more modules, the rebuild link appears:

However, given the advanced nature of this course, let's rebuild from the command line:
1. Shut down Tomcat (in Eclipse)
2. Run the following command:
ant smartbuild -Dlocal=no
Note: The -Dlocal=no parameter will automatically trigger the "update.database" task which creates
the necessary database structures required by the new modules.
Note: If the above command fails due to non-exported local changes in the application dictionary it
means you have probably made some application dictionary changes that you have not yet exported.
To prevent losing those on rebuild, run the
ant export.database export.config.script
command which will do so. If you don't care about the local changes, you can also force a rebuild
using the following command:
ant smartbuild -Dlocal=no -Dforce=yes
3. Refresh and rebuild the project in Eclipse
4. Start Tomcat again in Eclipse

Creating Project's Module Structure

Within our specific hotel scenario, we will be doing two things that differ significantly from the aspect of
modularity and packaging:
1. developing new elements that will add on top of the core functionality of Openbravo ERP Platform these will be part of a new module we need to create
2. customize certain core windows - this changed configuration of the core will have to be part of a new
template we need to create

Creating a New Module

A new module to be created will contain all new developments that add to the core functionality of
Openbravo ERP Platform but do not alter the core application in any way.
To create it, use the System Administrator role and navigate to Application Dictionary || Module and
create a new record within [Module] as indicated below:

Important fields to note:

Java Package - unique Java package that all classes will belong to (or one of its subpackage)
Version - the version of the module in the X.Y.Z format
Type - select Module since this one will include only new artifacts that will be developed
In Development - in order to be able to assign new artifacts to this module, it must be set as In
Development, hence check this box off.
Translation Required - since our module will contain UI artifacts (windows, messages, etc),
translation is required and the module's default language needs to be set (English)
Has Reference Data - check this off since our module will contain a dataset explained in a later
chapter
License Type and Text - for our module to be packaged and distributed, a License Type and Text
must be set.
Do NOT click the Register Module button since all students cannot register the same module (the
ones here designed for the course)

A few recommendations to follow while naming the modules:

First read the following articles:
http://wiki.openbravo.com/wiki/Naming_guidelines_for_modules
http://wiki.openbravo.com/wiki/Modularity_Concepts#Naming
Java packages: We suggest com.yourcompany.<functional area - sales, procurement, etc.>.<subfunctional area - if needed>
Author: The use of company name is suggested here as opposed to a person.
Any disclaimer that you want to mention in the description about the extent of the support you want to
provide on these modules.
Other good practices worth following are:
Do not use the name of the client in the code or in the module definition unless it is the top level
template with specifics to only one client
Do not use the name of the developer in the module definition

It is OK to develop in languages other than English as long as the language of the module is set
accordingly
If the module has been tested only in one database (Oracle or PostgreSQL), you might want to add
that as a note in the module description ("This module should be database independent; however it
has only been tested on Oracle | PostgreSQL").

Dependencies
At this point, our module will only depend on the foundational Openbravo 3.0 Framework so this needs to
be indicated inside [Dependency]:

This means that the end user will be able to install this module in any 3.0 instance of Openbravo
(Dependency Enforcement = Major Version) version 3.0.13451 or later. The user will not be able to
override this restriction (User Editable Enforcement = N), for example, this module will not be installable
in Openbravo v3.1 or v4.0.
Note: First Version is automatically entered by the system based on the version of Openbravo ERP you
are working in at the time. Leave this value unchanged.
DB Prefix
There are other database artifacts that are not defined within the Application Dictionary such as triggers,
functions or stored procedures. For the system to identify them as part of a module a unique prefix must be
used.
Let's define one within [DB Prefix] for our hotel scenario:

This way, if new stored procedure or a message is added, its name should be prefixed by HOTEL_.
Regardless of the Application Dictionary definition, all database artifact names will actually have to be
prefixed with this to indicate a clear association with a module.
Data Package
Later within the course, we will develop database artifacts such as new tables and columns. Openbravo
ERP Platform has a Data Access Layer built in which enables the programmer to access those database
objects through POJOs (Plain Old Java Objects). These objects get generated at compile time and stored
in memory at run time according to the definition inside the application dictionary. These definitions must
5

have a data package assigned that belonging Java objects will be a part of.
To define it, use the [Data Package] and enter at least one, a subpackage of the main module package:

Creating a Template
To create one, use the System Administrator role and navigate to Application Dictionary || Module and
create a new record within [Module] as indicated below:

Important fields to note:

Java Package - unique Java package that will uniquely identify this template. Note: Only because
this template will contain core customizations and include modules required for the Green Terrace
implementation, it makes sense to use the customer's name in its package name. This template itself
6

will not contain any generic reusable components.

Version - the version of the template in the X.Y.Z format
Type - since we will be customizing the core as well as building new things on top of it, our new
module must be of type Template
In Development - in order to be able to customize the core and have these changes recorded as
part of a template, it should be set to In Development status. Note: You should not have more than
one template in development at a time!
License Type and Text - for our module to be packaged and distributed, a License Type and Text
must be set.
Do NOT click the Register Module button since all students cannot register the same module (the
ones here designed for the course)

Dependencies
At this point, our template again depends on the foundational Openbravo 3.0 Framework so add it within
the [Dependency] tab as you did with the module previously.
Since we have installed the Localization Pack Spain and the Openbravo HQL Query Tool, it makes sense
that the Green Terrace Hotel Customization template depends on those as well so enter them accordingly
into [Dependency]:

Finally, the template should include the Hotel Management Module once it is packaged. To indicate this,
use the [Include] tab and add a new record:

Exporting New Structures

The new modules that we have just created currently only exist as records inside the database. To make a
copy on the harddrive that can be source controlled, use the following task:
ant export.database
This will create two new folders inside the modules/ folder:
modules/com.yourcompany.hotelmanagement
modules/com.greenterrace.openbravo.template
Later on, we will be developing Java classes so let's create a place for those. Software artefacts
can only be contained inside a module so we only need to create an src folder inside the
com.yourcompany.hotelmanagement folder:

Since we are developing in Eclipse, we need to tell it to include this new source folder in the build path.
First, refresh the openbravo project so that the newly created folders are detected. Then, right click on
the openbravo project and select Properties, then choose the Java Build Path option and switch to the
Source tab. There, click the Add Folder button and find and check the src folder within our new module:

Initial Client Setup

To be able to test our new developments, we need to create a dummy company that will contain some
dummy items (Rooms, Guests, etc) that we can use to play around and test the developments.
This dummy company could as well be the first prototype of the data for the particular client, the Green
Terrace Hotel.
Log into the Openbravo application, switch to System Administrator role and navigate to General Setup ||
Client || Initial Client Setup. Fill out the form as indicated below (select the password "openbravo" so that
an Openbravo instructor will be able to login if necessary):

Note: This process is crucial for the rest of the course so ensure it completes successfully! It may take up
to 10 minutes to complete so be patient.
Once it is done, log out and back in and test it by switching the role to the new Green Terrace Admin role.

Initial Organization Setup

Using the Green Terrace Hotel Admin role navigate to General Setup || Enterprise || Initial organization
setup window and create a new organization as shown:

10

Now, go to the General Setup || Enterprise || Organization window and double click the Barcelona
organization. There, check off the Allow Period Control checkbox, select the Green Terrace Hotel
Calendar in the Calendar dropdown and Save:

Finally click the Set as Ready button, leave the Cascade checkbox empty and confirm with OK.

Additional Roles
11

Since we will be defining certain fields that will be role-specific, let's define one extra role for a manager of
our Green Terrace hotel. Using Green Terrace Hotel Admin role navigate to General Setup || Security ||
Role window and create a new one as indicated:

Since it's not a Manual role, it will automatically inherit privileges from the Green Terrace Hotel Admin role
which is what we want.
The following items also need to be added:
[Org Access]: add the * and Barcelona organizations
[User Assignment]: add the Openbravo user
For more information on the above processes and other functional configuration topics, see the following
article: http://wiki.openbravo.com/wiki/Quick_Guide

12