Openbravo ERP Advanced

Development
Chapter 2 – Setup
v2.50.17

© 2008-2010 Openbravo S.L. 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.

1. Introduction
2. Local Environment
3. The Community Appliance
1. Starting Up the Appliance
2. Accessing the Appliance
1. The Application Itself
2. Command Line
3. File System
1. Ubuntu
2. Windows + Bitvise Tunellier
4. The Database
3. Performing Various Tasks
4. Hotel Scenario Introduction
1. Entities
2. E/R Diagram
3. Window Functionality
4. Window Customizations
5. Additional Functionality

Introduction
Before we start discussing advanced development artifacts of Openbravo ERP we need to
set up a few elements as well as introduce the Hotel Management module that we will be
developing.

Local Environment
In case of a live classroom course:
 The latest community release of Openbravo ERP must be used!
 If one does not arrive with Openbravo ERP pre-installed, we offer the use of the
virtual appliance that can be downloaded
from http://sourceforge.net/projects/openbravo and is also located on the USB
key provided. Install the VMWare
Player ( http://www.vmware.com/download/player/download.html ) that is
supplied on the USB key.
 Install pgAdmin III Postgres database administration tool found on the USB key
or downloadable from http://www.pgadmin.org/ . This tool will be used to access
the database, browse its content and execute SQL queries.
 In case of using Windows operating system and an appliance, install Bitvise
Tunnelier so that you can browse and upload files to the appliance. Find it
on http://www.bitvise.com/download-area or on the USB key provided. Linux OS
comes with SSH support already built into the Nautilus file browser.
 copy the OpenbravoERP-2.50MPXX-x86.vmware.zip file from the USB onto
your local harddrive and expand it
 open the expanded file using VMWare Player

In case of an online training:

 Use the "Open My Virtual Machine" button to open your private instance of the
Openbravo ERP application hosted on Amazon Elastic Cloud. The virtual machine
contains the latest community release of Openbravo ERP and will be used
to develop the assignments given within this course.  After clicking
the "Open My Virtual Machine" button, a new tab will open in the browser with
a URL similar to ec2-79-125-51-36.eu-west-1.compute.amazonaws.com.
Please save/bookmark this URL somewhere, you will need it later to connect
to your instance of Openbravo ERP.
 A local installation/virtual appliance should also be set up in order to be used
for testing and doing the HOWTO exercises. The HOWTO exercises should not
be run inside the virtual machine provided online.
See the following article for more information on how to use a virtual
appliance: http://wiki.openbravo.com/wiki/ERP/2.50/Openbravo_ERP_Installatio
n/Community_Appliance .
 Install pgAdmin III Postgres database administration tool
from http://www.pgadmin.org/ . This tool will be used to access the database,
browse its content and execute SQL queries.
 In case of using Windows operating system, install Bitvise Tunnelier so that
you can browse and download/upload files to the virtual machine. Find it
on http://www.bitvise.com/download-area. Linux OS comes with SSH support
already built into the Nautilus file browser so no additional tools need to be
installed.

Note: Openbravo Professional Subscription appliance is not suitable for use in this
course since the production nature of it does not fit the development purposes.

The Community Appliance

Here are a few tasks and tips that you will need to get around of using the community
appliance.

Starting Up the Appliance

Online course:
 1. the online course already comes with a deployed virtual instance on Amazon
Elastic Cloud so no configuration is necessary
2. simply press the Open My Virtual Machine button on the front page of the
course

Live course:
1. start the VMWare player and open the .vmdx file found in the
expanded OpenbravoERP-2.50MPXX-x86.vmware folder using the VMware
Player
2. find the Networking setting (Edit virtual machine settings) and set it
to NAT. Note: Not using the NAT Networking Adapter might cause the instance
to not have access to the Internet which is required later on to install modules.
3. start the appliance by pressing the Play button

Accessing the Appliance

The Application Itself

To access the Openbravo ERP application itself, point your browser to the URL
indicated by the appliance after it boots, e.g. http://192.168.255.130/ for local
virtual instances or something like http://ec2-79-125-51-36.eu-west-
1.compute.amazonaws.com for online virtual instances. To log in, use the following
credentials:
 username: Openbravo
 password: openbravo

Note: Do not change the password of this user in case an Openbravo instructor needs to
log in and troubleshoot your instance!

Command Line

To access the commandline of the appliance use ssh (linux) or one of the free ssh
tools for Windows found on http://www.putty.org/ (preferrably Bitvise Tunnelier which
you will need anyway to access the file system, see section below on how to use it). Use
the following credentials:
 URL: IP/URL indicated by the appliance (or the virtual machine's URL you
bookmarked earlier), e.g. ec2-79-125-51-36.eu-west-
1.compute.amazonaws.com
 username: openbravo
 password: openbravo

E.g. in Linux, the following command line is used to connect to the appliance:

$ ssh openbravo@ec2-79-125-51-36.eu-west-1.compute.amazonaws.com

In Windows, follow the Windows + Bitvise Tunnelier section below.

File System

To manage (create/upload/delete Openbravo ERP files) on the appliance, we recommend

you use a graphical file manager that supports SSH.

Ubuntu
Ubuntu (or any Linux using GNOME desktop) comes with a Nautilus file browser that
has built in support for browsing file systems through SSH. Go to File > Connect to
Server... and enter data similar to:

Then use "openbravo" (without the quotations) as a password to receive a simple file
manager interface:

Windows + Bitvise Tunellier

After installing Bitvise Tunnelier, run it to receive the front screen where connection
parameter can already be entered:
Before connection, check the Options tab and see the On Login section, Open
Terminal and Open SFTP should be checked off.
Click Login and it will open the terminal (command line) window AND a file
manager window.

The Database

The community appliance comes with no firewall configured and the Postgres

database listener wide open.

To connect to the database using the PgAdmin GUI, open the application and create a
new connection/server:
Note the following important fields:
 Host - the actual IP/URL of the appliance
 Maitenance DB - the name of the database, in case of the appliance this
is openbravo
 Username - in case of the appliance use tad
 Password - in case of the appliance use tad

Performing Various Tasks

Here are some handy command lines when developing on top of an appliance:
 move to the Openbravo ERP sources folder
# cd /opt/OpenbravoERP
 restart Tomcat
# su
# /etc/init.d/tomcat restart
# exit
 location of Openbravo context in Tomcat
# /var/lib/tomcat/webapps/openbravo
 location of Openbravo logs in Tomcat
# /var/lib/tomcat/logs (see openbravo.log, openbravo_hibernate.log
and catalina.out)
 create a folder
# mkdir {foldername}
 list files with details
# ls -al
 set ownership of AppsOpenbravo and tomcat context back to their corresponding
users (in case you accidentally compile the application
in superuser (su) mode)
# su
# chown openbravo:openbravo /opt/OpenbravoERP/ -R
 # chown tomcat:tomcat /var/lib/tomcat/webapps/openbravo/ -R
# chmod 770 /opt/OpenbravoERP/ -R
# chmod 770 /var/lib/tomcat/webapps/openbravo/ -R
# exit
 restart the network and re-obtain the IP (DO NOT PERFORM THIS ON THE
ONLINE VIRTUAL MACHINE! YOU MIGHT LOSE ACCESS TO THE
APPLIANCE!)
# su
# /etc/init.d/network restart
# exit
 see what IP is assigned to the virtual machine
# /sbin/ifconfig
 shutdown the virtual machine (DO NOT PERFORM THIS ON THE ONLINE
VIRTUAL MACHINE! YOU WILL LOSE ALL DATA!)
# su
# halt

Hotel Scenario Introduction

To make development exercises easier to understand and more realistic, the whole
course revolves around development of a miniature Hotel Management module. As in
a real life situation, the problem needs to be specified first, database structures defined
and window functionality described. In the end, we want a clear deliverable in a form of
a packaged module that can be distributed or installed at a client's site.

Entities
The following entities are new to existing Openbravo ERP functionality:
 Guest that can tie to a Business Partner to whom an invoice can be issued
o Custom Identifier such as a unique number for each guest
o First name
o Last name
o Business Partner - link to an existing Business Partner to whom the
invoice will be issued
o Guest Rate - daily rate the guest is entitled to (fixed list of options: A, B
or C)
 Room
o Number
o ARate - rate for regular guests that have stayed for more than 10 nights
within the last 6 months
o BRate - rate for guests that have stayed for more than 5 nights within the
last 6 months
o CRate - default rate for a walk-in guest
o Type - Single/Double/Suite
o Smoking - Y/N
 Stay - an overnight stay of a particular guest in a room
o Date In - date of the check-in
o Planned Nights - preplanned booking of a number of nights
o Date Out - date of the check-out
o Room Rate - the room rate used for a stay (A, B or C)
o Final Sum - sum calculated upon checkout based on the number of nights
stayed and the rate used
E/R Diagram

Window Functionality
To support the functionality indicated by the structures above, we will require two
windows:
 Guest/Stay
o Guest header tab
 manage guests
 Identifier needs to be automatically generated but can be
changed upon entry of a new guest
 the Rate field must be read-only to all users except the ones with
the Manager role
 have a button that enables recalculation of the guest's
rate based on their stays within the last 6 months
o Stay child tab
 Room dropdown should only list available rooms
 Room field should not be updatable
 Final Sum field should not be visible until the Date Out is entered
 Upon entering Date Out, Final Sum should be automatically
calculated
 Room:
o manage the list of rooms with their properties

Window Customizations
Our hotel application will also use the existing Business Partner window but requires
less functionality than is originally provided by Openbravo ERP. Therefore, we will cut
down the tabs and some fields of this existing window, this way changing the core.
Because our module is a template, this is allowed and the changes made will be
exported as an XML file called aconfiguration script. Upon exporting and packaging the
module, this configuration script will also be included. The following changes are
required:
 Hide (deactivate) these tabs:
o [Withholding]
o [Product Template]
o [Volume Discount]
o [Shipment Route]
 Within the main [Business Partner], hide these fields:
o Summary Level
o Expected Lifetime Revenues
o Share
o Volume of Sales
o Acquisition Cost
 Within [Contact], move the Email field up so that it will be located just after
the User field

Additional Functionality
The following additional functionality should be developed:
 the option to recalculate room rates for all guests with a click of one button
 have a background process that recalculates room rates for all guests every
night
 provide a CRUD webservice that exposes new hotel structures
 alert about guests who have overstayed their booking

Objective
Openbravo ERP 2.50 introduces the new concept of Modularity. Modularity provides developers with the
means to be able to develop, package and distribute their work in a structured and controlled manner.
For users of Openbravo ERP, Modularity makes it possible to download, install and update custom
developments.

This how-to describes how to create and package a new module. It is of particular interest as it
describes the first steps which should be followed in all of the other how-to in this developer's guide and
in Openbravo ERP custom development in general.

Introduction to Modularity
The objectives of modularity are:

 To make it easier to contribute to Openbravo ERP by allowing distributed and decoupled

development and maintenance of optional features.
 To provide the community with a rich set of extensions to meet their unique business
requirements without bloating the core product.
 To shorten the implementation cycles by enabling system integrators to develop very specific
functionality to meet the unique needs of a particular market.

A module is a piece of additional functionality that can be deployed optionally and independently on top
of Openbravo ERP. Examples of modules are: additional reports, additional windows, connectors, content
packs (translations, chart of accounts, list of tax codes, product categories, etc).

For a detailed description on the Openbravo ERP modularity concept, see the Modularity Guide.
This how-to will explain only the standard module type, because that is most relevant for the other how-
tos. The two other module types, Industry Templates and Packs, are not covered here.

All new development should be done as a part of a module. Only modules which are marked as In
Development can be used in the development process. A module can consist of the following software
artifacts:

 Application dictionary components: all new application dictionary artifacts must be associated
with a module. Application dictionary windows now have a field that enables you to link an
application dictionary component to a module.
 Software resources: these are artifacts not defined in Openbravo ERP itself but, for example,
Java classes, libraries, web resources (images, etc.), configuration files, etc. To maintain the
relationship with the module, software resources need to be located in the module's directory
inside the Openbravo ERP development project. Each module has its own unique directory.
 Reference data: modules can be distributed with their own set of reference business data, for
example, product categories, tax code, etc. The reference data is defined in datasets which can
be related to a module.

The process of developing a module has three main steps:

1. Register your module in the Application Dictionary and in the central repository.

2. Develop the artifacts included in your module. Depending on the functional specification and
technical design of your module it might include only one type of artifacts or a combination of
them. In following sections each type of artifact is described in detail.
3. Extract the .obx file of your Module and publish it in the central repository.

Steps 1 and 3 are common to all types of modules and straightforward. Step 2 depends on the
requirements of your module. It has not significantly changed from the way you have developed
Openbravo ERP code in previous releases to 2.50 but a few details that you need to know and that are
described throughout later in this document. In particular the development tasks (create/update the
database, build and compile the system, etc.) have been slightly modified to fit the modularity
paradigm.

From now on, every piece of Openbravo ERP code belongs to a module, including Openbravo ERP core
itself. You should do all your new developments through modules, including customizations. You can still
make changes directly in other modules -including Openbravo ERP core- but it is highly recommended
not to do that. It makes it much easier to maintain Openbravo ERP if you restrict code changes to
modules.

A module can be distributed and downloaded by other Openbravo ERP users via the central
repository.For more information about the central repository and distribution of modules, see
the Modularity Guide.

The following sections will discuss the main topic of this how-to: create and setup a module and package
it for distribution.

Creating a Module
The first step in the development process is to create a new module. From the Application menu,
select Application Dictionary || Module.
Note the following important fields: (for more details see the AD_Module table description):

 The format of the Version field is three numbers separated by two dots.

 The Java Package is a unique identifier of your module and has to match the Java package
naming rules as described in the Java Naming Conventions (names and package names). Be
careful when setting this value as you are not allowed to change it once your module is
registered in the central repository. If your module includes Java files they have to be packaged
within your module's Java package or in its sub-packages. Examples of Java packages for a
module
areorg.openbravo.examples.helloworld, com.yourcompany.yourPackage, org.yourfoundation.yo
urPackage.yourSubpackage, etc.
 The In Development option lets the system know that you are developing the module. Only
modules in development are exported by development tools and the system will raise an error if
you try to modify a component of a module that is not in development.
 The Default field option for a module marks that module as the one which is selected by default
when developing and when editing components in the Application Dictionary. You may be
developing more than one module at any one time, and specifying a default enables the module
you want to be selected by default.
 Select the Translation Required option if your module contains UI artifacts (window, field)
that have translatable elements.
The tabs at the top of the window enable you to define the module further:

 Include: is used by industry templates/packs, and is not covered by this how-to.

 Dependency: defines the module's dependency on other modules.
 Translation: is used for supporting translations, and is not discussed further in this how-to.
 Data Package: allows you to groups tables together. Data packages are used to determine the
Java package generated Java code (business objects).
 DB Prefix: relates database schema artifacts to modules.
 Naming Exceptions: is used during upgrades of previous versions of Openbravo ERP. It should
not be used for any other purpose.

In this how-to, we will create an example module, called Openbravo Howtos'. We will define the module
using the following three tabs of the Application Dictionary || Modulewindow:

 Dependency
 DB Prefix
 Data Package

The result of this howto will be a module which can be used as the basis for all subsequent
developments within the howto articles in the developers guide.

Dependency: Openbravo ERP core functionality is in itself a module, called core. All modules have a
dependency on Openbravo core. In the Dependency window, specify that the module is dependent on
core. (see also the AD_Module_Dependency description):

DB Prefix:at least one db prefix is required when a module also contains database artifacts (table,
column, constraints, etc.). Openbravo ERP determines the module of a database artifact by checking to
see if its name starts with one of the defined db_prefixes. As other howto's in the developers guide will
add database artifacts, let's specify at least one DB prefix.

For more information see the AD_Module_Dbprefix table description.

Data Package: Tables are linked to a module through the Data Package. The generated business object
for the new table will use the Java Package defined in the Data Package. Other howto's in the developers
guide will add new tables so there is a need to specify a data package as illustrated in the image below.
Develop your software artifacts
At this point you are ready to develop the software artifacts required for the functionality of the module.
While developing the relation to the module is maintained in different ways:

 Direct: for example a Window is directly related to a specific module.

 Indirect: a table belongs to a data package which again belongs to a module.
 By name: a new stored procedure is linked through a module by prefixing it with
the DB_Prefix of the module.

When you are ready with your custom development the next step is to export the module.

Creating a Source Directory

To develop manual Java code you need a src directory inside of your specific module:

The Java package in the source directory should start with the Java package of the module. So for this
case org.openbravo.howtos.test and org.openbravo.howtos.app would both be valid packages.

If using Eclipse, add the newly created module's src folder to the build path of the Eclipse project (Java
Build Path):
This makes it possible for Eclipse to build the code and have a full-functional Java editor when editing
the source code of your module.

Exporting a Module
Exporting a module creates a directory for your module under Openbravo ERP root directory and the
appropriate XML files for inclusion in the finished module. Modules that are not flagged as being in
development are not exported - remember that you must select the In Development checkbox when
you define a new module, otherwise it will not be exported.

When the development of the module is finished (or to deliver intermediate results), open a command
window/shell and navigate to the Openbravo ERP development project execute the ant
export.database command.

   Export database task will export all and only the modules set as in Development
ant export.database

Since we do not have any additional developments yet, only the corresponding folder structure and the
module descriptor XML files have been created at this point.
Openbravo ERP validates the database and module artifacts of a module when the module is exported
and packaged. See more information on the database validation step.

For a detailed description of this export.database task and other relevant Module related ant task see
the database ant tasks and module ant task descriptions.

Packaging a module
The last step in the process is to package the module and distribute it through the central repository or
sending it to an interested party directly.

To package a module, execute the command ant package.module -Dmodule=<modulePackageName>.

In the case of the howto module, the command would be:
ant package.module -Dmodule=org.openbravo.howtos

The output of the package.module task would roughly look like this:

$ ant package.module -Dmodule=org.openbravo.howtos
Buildfile: build.xml

package.module:
[echo] Validating Module...
[validateModules] 0 [main] WARN SystemValidation - Validation
successfull no warnings or errors

obx.export.database:

obx.export.config.script:

BUILD SUCCESSFUL
Total time: 48 seconds

As you can see in the output, the package step validates the module definition itself.

If the packaging process was successful, a new obx file is created in the directory in which this ant task
was executed. The name of the example module crated in this how-to isorg.openbravo.howtos-
1.0.0.obx. Note the obx file is in zip format so you can open it with any archive manager by first
renaming it to org.openbravo.howtos-1.0.0.zip.

Deploying/Compiling a module
Once you have created an .obx file, the final step is to compile and deploy it. Installing a module
compiles the Java sources, copies relevant files to the web application directory (images, etc.) and also
updates the database.

You can install a module from within Openbravo ERP:

1. Log in as System Administrator.

2. From the Application menu, select Application Dictionary || Application || Module
Management.
3. Select the module you want and click Install Now.
4. Follow the on-screen instruction to rebuild the application and restart the Tomcat server.

You can also install a module from the command line, using the ant task
ant smartbuild -Dlocal=no

after manually unzipping the .obx file into the OpenbravoERP/modules folder.

The Result
The result of this how-to is a correctly set up and packaged module which you can then use as the basis
for the other how-tos in this Developers Guide.

Openbravo ERP Advanced

Development
Chapter 3 – Modularity & Initial
Client Setup
v2.50.17

© 2008-2010 Openbravo S.L. 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.

1. Reference
2. Introduction
3. Creating Module Structure
1. Creating a New Module
1. Dependencies
2. Data Package
3. DB Prefix
2. Creating a Template
1. Dependencies
3. Other Modules
1. Installing Localization Pack Spain
2. Rebuilding the Application
4. Initial Client Setup
1. Initial Organization Setup
2. Additional Roles
5. Further Reading

Reference
Before starting with this chapter get acquainted with modularity concepts by reading the
following chapters:
  http://wiki.openbravo.com/wiki/ERP/2.50/Developers_Guide/Concepts/Modularity
 http://wiki.openbravo.com/wiki/ERP/2.50/ModularityVideos/Install_Module
 http://wiki.openbravo.com/wiki/ERP/2.50/Developers_Guide/How_to_define_user
s_roles_privileges_menus

Introduction
Modularity is an important feature of the Openbravo ERP, making the system very
flexible, modular and maintainable. Introduced in version 2.50 of the Openbravo ERP,
modularity is a new approach to development, packaging and distribution of
customizations done to the application. Before we make any changes to Openbravo ERP
or develop any additional functionalities, we need to create a module to which these will
belong. An additional benefit to this concept is that we will be able to neatly package
all our 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 Spanish
Localization Pack will be a prerequisite for the Initial Client Setup of our Green
Terrace Hotel.

Creating 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 - 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 but do not alter the core application in any way.

To open 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 belonging 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
article: http://wiki.openbravo.com/wiki/Naming_guidelines_for_modules
 Java packages: We suggest com.yourcompany.<functional area - sales,
procurement, etc.>.<sub-functional area - if needed>. <type of module -
window, report, process, etc.>.
You can
see http://wiki.openbravo.com/wiki/Localization_Process#Localization_Java_pac
kage_naming_conventions as an example of what we are proposing for
localization packages.
 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 core so this needs to be indicated
inside [Dependency]:

This means that the end user will be able to install this module in any 2.50 instance of
Openbravo (Dependency Enforcement = Major Version) version 2.50.18445 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 v2.60 or v3.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.

Data Package

Later within the course, we will develop database artifacts such as new tables and
columns. Openbravo ERP 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 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, usually a subpackage of
the main module package:

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, when a new trigger 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.

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
 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 core so this needs to be indicated
inside [Dependency]:
At the same time, the template should include the Hotel Module once it is packaged. To
indicate this, use the [Include] tab and add a new record:

Other Modules
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.

Installing Localization Pack Spain

For the purpose of this exercise 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.

Rebuilding the Application

Before the newly installed module can be seen, the application needs to be rebuilt
(recompiled). To do so, go back to the [Installed Modules] and click the rebuild
now link.

This will pop up a new window with the confirmation button. By clicking it, the
compilation starts which will take several minutes resulting in a window like:
Restart the servlet container and log into the application. Use the role switching dialog
to switch the language to Spanish. Navigate to Configuracion General || Entidad
|| Crear Entidad to see the interface in Spanish with additional modules available now
as part of the Initial Client Setup:
Similarly, other modules that are available in the central repository can be downloaded
and installed.

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 a particular
client.
Log into the Openbravo ERP application, switch to System Administrator role and
navigate to General Setup || Client || Initial Client Setup. Fill out the form as
indicated below:
Fields to note are:
 Client – the name of the new company
 Client Username – the username that will be created belonging to the Green
Terrace Hotel Admin role
 Password - password for the client admin user that will be created. Choose
something easy like "openbravo" since security is not an issue in case of this
training instance.
 Include Accounting – if the company will use accounting. Let's put Yes here in
our case.
 Accounting File – if the company is using accounting, the chart of accounts CSV
file should be selected here. These are downloadable
fromhttp://sourceforge.net/projects/openbravo/files/04-openbravo-accounting/ .
However, Spanish Localization pack that we installed earlier also contains a
Chart of Account which can be seen under the Reference Data section so leave
this empty since we will select one there.
 Reference Data - items checked here will be pre-filled into the newly created
client so you don't have to create them by hand. Check the following required in
our case:
 Standard document types for orders, invoices, etc. and settings - core - English
(USA) - basic document type for vital documents (orders, shipments, invoices,
etc), part of the core
 Taxes: configuration for Spain (Impuestos para España) - predefined taxes for
Spain, part of the Localization Pack Spain
  Plan general contable 2007 (General) - Chart of accounts: PGC 2007 General -
generic chart of accounts for Spain, part of the Localization Pack Spain
 Business Partner – this should be checked as one of the dimensions for
accounting
 Product – this should be checked as another dimension for accounting
 Project - this can (optional) be checked as another dimension for accounting

Note: This process is crucial for the rest of the course so ensure it completes
successfully!

Once it is done, use the role switcher in the top left corner of the menu to switch roles.
You should be able to select the new Green Terrace Hotel Admin role now and confirm
with OK:

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:
Fields to note are:
 Organization – the name of the new organization within the client you are
logged in with (Green Terrace Hotel in our case)
 Organization Username – the username that will be created belonging with
privileges to access the new organization
 Organization Type - legal type of organization, select Legal with accounting
 Location/Address - input the principal address of the new organization
 Include Accounting – if the organization will use accounting. Put No her since
in this case, the accounting will be done on the top client level where we have
already defined it.
 Accounting File – leave empty since accounting was already defined on the top
client level.

Now, go to the General Setup || Enterprise || Organization window and double click

the Barcelona organization. There, check off the Allow Period Control checkbox, select
theCalendar, Save and finally click the Set as Ready button:
and, leave the Cascade checbox empty and confirm with OK.

Additional Roles
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 toGeneral Setup || Security || Role window and create a new one as
indicated:

Since it's a non-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

Further Reading
 http://wiki.openbravo.com/wiki/ERP/2.50/Configuration_Manual/Getting_started

Languages: 
English  |  Italiano | Translate this article...
 Contents

 [hide]

1 Overview
2 Before you start
o 2.1 System requirements
o 2.2 Configure your instance
o 2.3 Concepts
 2.3.1 Artifacts in an Extension Module
 2.3.2 Types of Extension Modules
 2.3.3 Packaging and .obx files
 2.3.4 Module Manager Console (MMC)
 2.3.5 Central Repository
3 Introduction to the process of developing a Module
4 Register a Module
5 Development of Module artifacts
o 5.1 Application Dictionary Components (AD components)
 5.1.1 Table and column
 5.1.2 Window, Tab and Field
 5.1.3 Reference
 5.1.4 Report and Process
 5.1.5 Form
 5.1.6 Message
 5.1.7 Text interfaces
 5.1.8 Element
 5.1.9 Field category, Auxiliar input, Callouts and
Validations
 5.1.10 Model - Implementation mapping
o 5.2 Software Resources
 5.2.1 Database schema objects
 5.2.1.1 Exceptions
 5.2.2 Java classes, other Openbravo MVC stuff and jar
libraries
 5.2.3 Web Static content (css files, images, javaScript)
 5.2.4 Config files
o 5.3 Reference Data
 5.3.1 Translations
 5.3.2 Chart of Accounts (CoA)
 5.3.3 Standard Reference Data
o 5.4 Module Scripts and Build Validations
o 5.5 Configuration Script
o 5.6 Development tasks
6 Publish the .obx file of a Module
7 Advanced concepts
o 7.1 Version numbers and how dependencies and includes are
managed
 7.1.1 Dependency types
 7.1.1.1 User Editable Enforcement
o 7.2 Model - Implementation concept
8 Example on how to create and package your module

Overview
Openbravo 2.50 comes with the new concept of Modularity: the ability for developers to build, package
and distribute Extension Modules and for users to install, uninstall and update Extension Modules.
An Extension Module is a piece of additional functionality that can be deployed optionally and
independently on top of Openbravo ERP. Examples of modules are: additional reports, additional
windows, connectors, content packs (translations, chart of accounts, list of tax codes, product
categories, etc).

The objectives of modularity are:

 Making it easier to contribute to Openbravo ERP by allowing distributed and decoupled

development and maintenance of optional features.
 Providing the Community with a rich set of extensions to meet their unique business
requirements without bloating the core product.
 Shorten the implementation cycles by enabling system integrators to develop micro-vertical
templates.

This document contains the developers manual for developing Openbravo ERP Modules.

Before you start

System requirements
To develop a module you must use version 2.50 or later of Openbravo ERP.

Configure your instance

There are some new requirements in 2.50 when configuring the environments. Please review
the Development Stack Setup documentation before going ahead.

Concepts
Before you start it's also required to understand some new concepts. These concepts are described in
detail in following sections in this document.

Artifacts in an Extension Module

There are four types of artifacts that can be included in an Extension Module:

 Application Dictionary components: Metadata that describe Openbravo ERP such as

Windows, Tabs, Fields, Messages, etc.
 Software Resources: Openbravo ERP components not expressed as metadata such as xml
definition of database schema objects, java classes, jar libraries, XML files, etc.
 Reference Data: Business information referred by transactions and that tend not to change
frequently such as Charts of accounts, tax codes, banks, product categories, etc. They can be
defined at system, client or organization level.
 Configuration Script: Changes in Application Dictionary Components applied to other modules
to support a specific set of business processes, such as Hide / show tabs or fields, replace
standard processes, etc. Only meaningful changes are allowed.

Openbravo platform itself can not be modified through modules. In particular you are not allowed to
modify wad (src-wad code) in a module. It should not be a limitation since the platform is designed to
be extensible.

Types of Extension Modules

There are three types of Extension Modules:

 Modules: Base content container. Within a Module you can include all types of artifacts
but Configuration Scripts: Application Dictionary components, Software resources and Reference
data. Modules are the way to add new elements to Openbravo ERP. In a Module you cannot
 modify elements of other modules -including core-. The reason of that is to avoid crossed
dependencies between them.
 Packs: a Pack is a collection of modules and no more. They are intended to simplify deployment
and to encourage fine grained modules. Special packs are localization and verticalization packs.
 Industry Templates: a combination of a Pack and a configuration script that is able to modify
the behavior of AD components in Modules included in the Pack.

The three of them are generically referred as Modules.

Packaging and .obx files

All the content of a module -code, utility files, data- is packaged together in an isolated folder for each
module. All the content in that folder is related to and only related to that module. There is a new folder
within the main Openbravo folder called modules where all the modules that you have installed or
developed are located. For each module there is a folder identified by the module java name. In that
folder the source code structure of openbravo (config, src, src-db, lib, etc.) is replicated as required to
store the content of the module.

Modules are distributed as .obx files which are compressed files of the module folder. You can directly
decompress it using a zip tool to browse its content.
Module Manager Console (MMC)
This is a new window in Openbravo ERP where System administrators can see installed Extension
modules in their instances, and where they can install new ones and uninstall or update the ones that
are already installed.

You can find more detailed information about how to operate MMC in the Modules Management
document
Central Repository
The Central Repository is a system embedded in the Openbravo Forge to provide services related to
Openbravo ERP Modules for developers and users. Detailed description about Central Repository can be
found in Publishing Modules document.

Introduction to the process of developing a Module

The process of developing a Module has three main steps:

1. Register your Module in the Application Dictionary and in the Central Repository.

2. Develop the artifacts included in your Module. Depending on the functional specification and
technical design of your module it might include only one type of artifacts or a combination of
them. In following sections each type of artifact is described in detail.
3. Extract the .obx file of your Module and publish it in the Central Repository.

Steps 1 and 3 are common to all types of modules and straightforward. Step 2 depends on the
requirements of your module. It has not significantly changed from the way you have developed
Openbravo ERP code in previous releases to 2.50 but a few details that you need to know and that are
described throughout later in this document. In particular the development tasks (create/update the
database, build and compile the system, etc.) have been lightly modified to fit the Modularity paradigm.

Be aware that from now on every piece of Openbravo ERP code belongs to a module, including
Openbravo ERP core itself. You should do all your new developments through modules, including your
customizations. Still you can do changes directly in other modules -including Openbravo ERP core- but it
is highly recommended not to do that. Maintenance will be dramatically better if you keep your changes
isolated by doing them through modules.

Following sections will describe each step in detail.

Register a Module
The first thing you have to do is to create a new Module entry in the Module Window within the
Application Dictionary menu folder.

There are some details that you need to be aware of:

 Each module has its own native (base) language. In following sections the translation process is
described, by now just choose the language you prefer to develop the UI of your module. Of
 course if you choose English it will be easier to disseminate (eg. to find people to translate it to
other languages).
 Name, description and help are the properties used to explain in the Central Repository what
your module is. Write them in natural style using the native language you have chosen.
 The Version Number is composed by three numbers separated by two dots to match
the Openbravo template for version numbers. In this field you need to have the current version
you are working on (there might be multiple versions of your module). Later in this
document Version Numbers are explained in detail.
 The java package is a unique identifier of your module and has to match the Java packaging
names rules as described in the Java spec. (names and package names). You need to carefully
set this value because you are not allowed to change it once your module is registered in the
Central Repository. If your module includes java files they have to be packaged within your
module java package or in subpackages within it. Examples of java packages for a module are
org.openbravo.examples.helloworld, com.yourcompany.yourPackage,
org.yourfoundation.yourPackage.yourSubpackage, etc.
 Choose the type (Module, Pack, Template) as described in the Concepts section
 In development is a boolean property to let the system know that you are developing on that
module. Only modules in development will be exported by development tools and the System
will raise an error if you try to modify some component on a module that is not in development
 Although you might have more than one module in development you can set which one is
choosen by default when developing. This is just a way to set a default value for the module
when you edit the Application Dictionary
 Some modules will not have UI (eg. a connector to a banking system or a web service) so there
is no need to translate them
 If your module is a translation module of another module you have to check this flag to allow
users to search for translations. Later in this document there is a full description of how to
create a translation module.
 If your module has Chart of accounts you have to check this flag to allow the System to use
them during the Initial Client/Organization Setup processes. Later in this document there is a
full description of how to add a Chart of Accounts to your module.
 If your module has standard Reference Data you have to check this flag to allow the System to
use them during the Initial Client/Organization Setup processes. Later in this document there is
a full description of how to add a standard Reference Data to your module.
 You have also to choose the license you are using to distribute your module. Choose one license
type from the drop-down list and write the license agreement that will be shown to the user
when installing or updating your module. Be aware that Openbravo does not supervise the
content of your module nor the license you have choosen. You are responsible to set this
information properly
 The author of the module will be shown to the User when browsing the Central Repository and
when installing. Also the User will be able to navigate from there to the module url
 If you are working on a new version of your module you can explain what are the changes this
new version includes (fixed bugs in minor versions, new features in major ones) in the "Update
information" field.

The Include tab is intended only for Packs and Industry Templates. In this tab you include all the
modules that are members of the Pack. You can only choose from the ones that you have installed in
your instance. You have to provide the Version Number for each of them following Openbravo template
as described. In a later section there is a description of how the system manages Version
Numbers of Includes (for Packs and Industry Templates) and for Dependencies (for Modules).

The Dependency tab is intended only for Modules. In this tab you declare all the Modules that your
Module depends on. It is of paramount importance that you declare them properly since the system will
check that dependencies are met when the User installs or updates your module. It is also important to
declare them as soon as you are aware of that because some tools and processes in the development
process takes into account dependencies and the result might be wrong if they are not declared when
developing your module. You declare dependencies along the modules you have installed in your
instance. Tipically a module will depend on core (Version no. 2.50.0000 or higher) and eventually in
other modules. You have to provide the Version Number for each Module it depends on following
Openbravo template. Optionally you can provide a second Version Number(higher than the previous) to
express that your Module depends on any Version Number of that module between the two provided.
Later in this document there is a complete explanation of Version Numbers and how dependencies and
includes are managed.

There is no need you to edit the Translation tab. It is a tool for translators and will be described in
the translation section.

If your Module includes a table in the Application Dictionary then you need to register one (or
many) packages in your Module. For a full description on how packages are used look at the DAL
developers manual. For each package you have to set the next properties:

 Name, that will be used in the xml entities of tables assigned to it

 Description, used to explain what your package is for
 Java name, that has to match the Java packaging names rules as described in the Java spec.
(names and package names). It should be equal to Module package name (if there is only one
package) or a subpackage of it.

If your Module includes any database schema object (a table, a stored procedure, etc.) or an AD
message then you need to define the DB_Prefix. This is a seven characters length string. All your
database schema object names need to start with this prefix so it needs to match Oracle and PostgreSql
naming requirements (case insensitive and stored in uppercase, alphanumeric characters and start by
an alphabetic character). You can only register one DB_Prefix, just Openbravo core Module is allowed to
have more than one.DB_Prefix is needed to guarantee that there are no naming clashes when installing
modules.

Once you have completed the set up of your Module then you need to register it in the Central
Repository. It is needed to ensure that your DB_Prefix and your java package are not already registered
by other Modules and it is important to do it even you don't plan to publish your module. More
information about this process can be found here.

Once you have completed the registration of your module you are ready to start developing your
artifacts!

Development of Module artifacts

As stated in the Concepts section there are four types of artifacts: Application Dictionary Components,
Software resources, Reference Data and Configuration Script. The requirements of your module and its
technical design will define the needed artifacts to build your module. This document explains the details
you need to be aware for each type of artifact, one by one, related to modularity. It does not explain
how to use them together to build solutions, it is described in the Openbravo Developers Guide. At the
end of this document there is an explanation of a number of simple "Hello World" examples that cover
all different type of solutions.

Application Dictionary Components (AD components)

Most of AD components can be included in your module but a few exceptions that are explained later in
this section. The general rule to describe how Applications Dictionary components are included in your
module is simple: set the module field of that component to your module. If you only have one module
in development or you are working in your default module it will be done automatically by the system.

Only modules marked as "in development" are available when you edit an AD component. If you change
a property in a AD component that is not in development the system will raise an error to avoid you to
perform not intended changes.

Translations are managed in a particular way and you don't need to take care about translations when
developing. There is a detailed description on the translation process in theTranslations section. But
remember that your module has a native (base) language so the UI components (Windows, tabs, fields,
elements, messages, textInterfaces, etc.) that you develop have to be created in that language.

Access information is not included in modules so you can forget it when developing your module. In a
later section it will be explained how to include a particular configuration for openbravo rbac (role based
access control).

There are some details on top of the general rule that you should understand to have better control of
the content of your module. It is worth to review each type of AD component.

Table and column

Registering tables in the AD is the first exception to the general rule. Tables are not assigned directly to
a module but to a package in a module. It is needed by DAL to properly manage packaging of generated
entities and xml naming. Only packages of "in development" modules are available when you edit a
table. The module of a table is the module of the package of a table.

Columns are assigned by default to the module of their table. But you might want to add in your module
a column within a table in a different module (eg. add a new column to the M_Product table in the core
module). To do that you are forced to use a naming rule for that column: its physical name
(ColumnName property) has to start by the prefix "EM_XXX_" where "XXX" is your module DB_Prefix.
"EM" stands for External Module. The Create Columns from DB process has into account all this rules
when importing columns from the database. The same rule is applicable for Name property which is
used to generate DAL's properties, therefore must be unique among different modules.

Window, Tab and Field

Window, Tab and Field follow the general rule. The three of them are linked to a module. By default
when you add a tab to window it will be linked to the module of its window and when you add a field to
a tab it will be linked to the module of its tab. This is true but when the window or tab modules are not
in development. Then the defaulted module will be proposed. The Create fields process has into account
all this rules when creating fields from table columns.

When editing the field sequence the system will guarantee that you do not change the sequence number
of fields that are not in you module, so if you add a new field in a tab of other module the sequence
number of the original fields will not be modified. If you edit manually this information be aware that
you can not modify information in a module that is not in development. It also applies if you are adding
an additional tab to a window in other module.

The tab class and mapping is automatically managed by the system and you not need to take care about
it. In a later section it is explained how Class and Mapping are managed and what you can do to add
additional entries there.

Reference
There are four types of references: Data type, List validation, Search validation and Table validation. In
Openbravo 2.50 only List validations and Table validations can be included in a module different to
Openbravo core. Data types and Search validations will be supported in modules in future releases
(currently it requires to modify Openbravo WAD).

All the values included in a List validation are included in the module where the List validation is defined.
In Openbravo 2.50 you can not add in your module new values to a List validation in a different module
nor modify the values included in it.

Report and Process

Reports and Processes follow the general rule. You can declare a new process or report in your module
by just creating a new entry in the Report and Process window and linking that entry to your module. All
parameters in a Report or Process will be included in the module where the Report or Process is
declared.

For manual report and processes it is necessary to define the process mapping, this mapping can be
anything within the module's package, for example/org.mycompany.mymodule.report/MyReport.html.

Form
Forms follow the general rule too. You can declare a new form in your module by just creating a new
entry in the Form window and linking that entry to your module.

For forms it is necessary to define the form mapping, this mapping can be anything within the module's
package, for example /org.mycompany.mymodule.form/MyForm.html.

Message
Messages follow the general rule but with an additional detail you need to take care. You can declare a
new message in your module by just creating a new entry in the Message window and linking that entry
to your module, and the search key of the message has to start by your module db prefix (to avoid
clashes between messages from different modules). It means that you can not include in your module a
message with a numeric search key to be raised by a pl/sql object through the
RAISE_APPLICATION_ERROR function.
Text interfaces
Text interfaces window usually is not edited manually but entries are automatically generated by the
translation process when it parses files to be translated. This process takes into account the packaging
of the file being translated and the text interface entry is properly assigned to the module. This process
should be transparent for developers but you can browse the entries that your manual developments
have created and edit them.

There is a detailed description on the translation process in the Translations section.

Element
Elements are usually automatically generated by the Synchronize terminology process when you create
new columns. This process takes into account the name of the columns that you have included in your
module and searchs in your module and the modules your module depends on for an element with that
column name. If it is found your column will be linked to that element, if not a new element will be
created in your module. This process should be transparent for developers but you can browse the
elements included in your module and edit them.

Field category, Auxiliar input, Callouts and Validations

These four Application Dictionary components follow the general rule too. You can declare a new
component of them in your module by just creating a new entry in the proper window and linking that
entry to your module.

Auxiliar input name must start with the module's DBPrefix.

Model - Implementation mapping

Model - Implementation mapping is generalization of the Model-Object concept that was present in
previous releases. You can see a detailed description in the explanation of theModel - Implementation
concept.

Through this new window you can include in your module the entries you need to add to the web.xml file
of Openbravo context.
Model - Implementation mappings follow the general rule. You can declare a new entry in your module
by just creating a new record in the Model - Implementation mapping window and linking that entry to
your module. All mappings and parameters assigned to it will be included in the module where the Model
- Implementation mapping is declared.

Software Resources
To develop your module you may require to include some software resources. Software resources are
Openbravo ERP components not expressed as metadata such as xml definition of database schema
object, java classes, jar libraries, XML files, etc. All you need to add to your module has to be packaged
within openbravoMainFolder/modules/yourModuleJavaName (eg. for the module
org.openbravo.examples.helloworld the packaging
is/home/user/src/openbravo/modules/org.openbravo.examples.helloworld in a linux box
or c:\openbravo\modules\org.openbravo.examples.helloworld in a windows one). Within this folder you
have the standard openbravo folders to hold your software resources (src, src-db, lib, etc). See the
image in the packaging section for details.

The build process of Openbravo has been modified to take into account the new source code structure
that now is split into modules. Be aware that this concept is completely different from the srcClient that
Openbravo used in previous releases: you are not allowed to physically overwrite a file in Openbravo
core distribution. In fact, the packaging of your software resources should be located in
com.yourCompany.xxx or org.yourCompany.xxx so you will not use org.openbravo.xxx to package your
code any more.

Similarly to AD components, although this general rule for packaging is applied to all software resources
there are some details for each type of software resource (Database schema objects, java classes, jar
libraries, web static content, etc.) that you need to be aware when developing your module.

Database schema objects

The typical flow to add a new database schema object (table, column, constraint, index, trigger, view,
stored procedure, function) or modify it in Openbravo ERP is as it follows:

 a developer uses her/his preferred tool as database client for development in Oracle or
PostgreSql
 using sql scripts or GUI tools she/he creates or modifies the database schema object in the
database following Openbravo standards (look at the Openbravo Developers Manual for details).
 if the database schema object is mapped with any Application dictionary (Tables&Columns,
Reports&Processes) then the developer import the new db schema object from the database to
the Application Dictionary. This process adds some new lines in AD tables. After that the
developer usually adjusts the imported information -eg. running the synchronize terminology
process- and complete AD information to fully describe the solution she/he targets. It might
require as well to create some Openbravo code (java files, xsql files, etc.) to complete the
solution
 once the solution is fully described the developer builds the system to test that it is working as
desired
 the last process is to export the database to xml files through DBSourceManager. This tool
export every database schema object to a xml file that uses a common syntax for both Oracle
and PostgreSql so you can have different development environments commiting to the same
line of code. Application Dictionary data is also exported in this process. So there are two
different types of xml files exported by DBSourceManager: model (db schema objects) and
sourcedata (Application Dictionary metadata).

From a modularity perspective there is no need you to do any additional task to take care of Application
Dictionary metadata since it is managed by the system as described in the previous Application
Dictionary Components section. But to avoid naming clashes in the database and to allow
DBSourceManager to kwow the module of not mapped database schema objects it is required to follow
the next naming rule for database schema objects:

 All main objects (tables, triggers, views, functions, stored procedures) have to start by your
module db_prefix followed by an underscore ("_") symbol (eg. MYMOD_MYTABLE,
MYMOD_MYPROCEDURE, etc.).
 Subparts of main objects (columns, constraints, indexes) are supposed to belong to the module
of the main part except if their name starts by "EM_" + db_prefix + "_" (eg.
EM_MYMOD_MYCOLUMN, EM_MYMOD_MYCONSTRAINT, etc.). EM stands for External Module.
So you can use standard column names in your tables (eg. C_BPARTNER_ID, M_PRODUCT_ID,
NAME, etc.) but if you want to add in your module a "part" (column, constraint, index) to a table
in another module you need to use the prefix "EM_" + db_prefix + "_" for the name of that
part. In any case, constraints and indexes in the same module and their table must start with
the module's db_prefix, this is in this way because their name must be unique in the whole
database.
And that's all. Following this simple rule you can include in your module as many database schema
objects as you want. But be aware that you can not modify database schema objects in other modules
as it would break the main rule: "a module can not modify components in other modules".

When DBSourceManager exports the database it will only take into account modules "in development",
the other ones will not be exported. The exported xml files will be located within the src-db/database
folder within the module folder. Look at packaging to see an example.

At the end of this document there are some examples explained that show how to include in your
module any type of database schema object. You can use them as a reference to develop your module.

Exceptions

It is possible to define database schema objects within a module that do not follow the naming rules
explained in the section above. This is specially useful in order to move to modules existent Openbravo
ERP instances in older versions.

When a database schema object is defined as an exception for a module it is exported to that module
instead to the one that should be according to its name and the naming rules.

Exceptions are defined in Application Dictionary || Module || Module >> Naming Exceptions tab
which contains two fields:

 DB Object Type: Defines the database object type (table, function, index...)
 Object name: It is the database object name. Note that it is the name in database, not in
Application Dictionary.

Notice that these are exceptions and they should be avoided if possible. Take also into account that a
module with exceptions will not be shareable.

Java classes, other Openbravo MVC stuff and jar libraries

Java classes, other Openbravo MVC stuff (html, xml and xsql files) and jar libraries follow the general
rule to add software resources in your module. You have to package this code within the src folder
located in your module folder.
When Openbravo ERP builds the system it will dinamically add to its java project all the src folders within
all installed modules as java resources of the project. It uses an intermediate location, build folder, to
generate code from xsql files and to compile all java resources and put them together. You can include
in your module jar libraries made by you or by any other third party and use them along your code. All
jar libraries included in the lib folder are added to the classpath at compilation time and finally deployed
to the openbravo context.

After the generation of code and compile process the build process deploys all the content to the
openbravo context in the servlet container. There are two modes of deployment -class and war- that are
explained later in the Advanced Concepts section.

Web Static content (css files, images, javaScript)

If you need to add some web Static content (css, images and javaScript) to your module you have to
place these resources in the web folder of your module, within a folder named as the java package of
your module to avoid clashes of files when deploying resources from different modules.

When the system is built all files in the web folder of your module are copied to WebContent and from
there it is deployed to openbravo context in a standard way so this resources can be accessed from the
pages in your module by referencing them. Take into account that xmlEngine performs an automatic
translation of urls through a replace of "../../../../../web" (replaceWhat parameter) by
"@actual_url_context@/web" (replacWith parameter), being "@actual_url_context@" the absolute path
to your openbravo context (eg. http://localhost:8880/openbravo).

The Solitaire module is designed to demonstrate how to include typical web static content in your
module. Through this example it is simple to understand how it works. For example, this is a snippet of
Solitaire.html to reference to solitaire.js file that is located within
the web/org.openbravo.examples.solitaire folder of Solitaire module:
<script language="JavaScript"
src="../../../../../web/org.openbravo.examples.solitaire/solitaire.js"
type="text/javascript"></script>

At execution time, once openbravo context is deployed and loaded you can get solitaire.js javascript
library from @actual_url_context@/web/org.openbravo.examples.solitaire/solitaire.js. When the main
page of Solitaire module is delivered, xmlEngine will replace "../../../../../web" by
"@actual_url_context@/web" and by so properly referencing to the available resource.

Of course you can also reference to other web static content resources included in core or other
modules. In that case remember to explicitily declare the dependency to that module.

Config files
You might also need to include some configuration files in the config folder of your module. These files
will be copied to WebContent/WEB-INF when the system is built and deployed to openbravo context.

For example, in HelloWorldService module there is file named org.openbravo.examples.webservice-

provider-config.xml within the config folder. This file is copied to openbravo context and by this mean
the class that implements the webservice is declared.

To avoid clashing of files deployed by different modules files within config-folder should be prefixed with
the PackageName of the module.

Reference Data
Openbravo Modularity supports Reference Data: business information referred by transactions and that
tend not to change frequently such as translations, charts of accounts, tax codes, banks, product
categories, etc. They can be defined at system, client or organization level and it will define when they
are loaded into the instance: System information will be loaded at intallation time while Client and
Organization information will be loaded during the "Initial Client/Organization Setup" or "Enterprise
module management" processes.

Reference data modules are also versioned and can publish updates and upgrades during their life cycle.

There are three types of reference data supported: Translations, Chart of Accounts and standard
Reference Data.

Translations
Translation modules are a special kind of module. They have to be marked as "Is translation module" in
the Module window. No other contents than translations are allowed in translation modules, and only
translations for one module to only one language, the native language declared for the module (eg.
translation for core module to Spanish, translation for HR module to French) . Translation modules only
depend on the module they translate.

Create a translation module is a straightforward process. First you have to create your module as usual.
Remember to define it as "translation module" and define the its native language as the language you
are going to translate to, and to use the native language of the module writing its name, description,
etc. Keep unchecked the other properties related to reference data (Translation required, Has chart of
accounts and Has reference data). This module does not need any Includes, Data packages and DB
prefix and will only depend on the module version you are translating.

Then create the main folder of your module -named as its javapackage- within modules folder, you can
do it manually or just by executing export.database Ant task (remember that the module has to be In
development).

Then all you have to do is install the module you plan to translate and declare the dependency of your
translation module to this module, and follow the standard translation process following this document.
Take into account that from release 2.50 the export languages process splits the xml files in different
folders for each module installed: core is exported directly to the language folder (eg. es_ES) and any
other installed module will be exported to a folder named with module package name within the
language folder (eg. es_ES/org.openbravo.examples.helloworld). Once you have completed the
translation you have to copy the translated xml files of the translated module -only these ones- to
referencedata/translation folder within your module folder, and package it as usual by executing the ant
task package.module -Dmodule="yourModuleJavaPackage" that will create an .obx file that is ready to
be published or distributed.

Translation information is always at System level. When a translation module is installed the process
takes care of all details to import a transalation pack: it will mark the Language as System Language if it
was not and will load all translations in Openbravo Application Dictionary.

Chart of Accounts (CoA)

Tipically you should add just one Chart of Account in your module, although you can create as many
modules including CoA as you want and then put them together in a pack if needed. Chart of Accounts
are stored in a particular .csv file, please read this explanation to learn more about how to create a .csv
file for a Chart of Accounts and test it is ok.

It is easy to create a module including a Chart of Accounts once you have prepared the .csv file. All you
need to do is create a new module and mark as checked the Has a chart of Accounts property. Keep
unchecked the other properties related to reference data (Translation required, Is translation
module and Has reference data). This module does not need any Includes, Data packages and DB prefix
and will only depend on the core version you are using (the structure of the .csv file is defined in core).

Then create the main folder of your module -named as its javapackage- within modules folder, you can
do it manually or just by executing export.database -Dmodule=yourModuleJavaPackage ant task
(remember that the module has to be In development). Withing the main folder you have to create the
subfolder referencedata (all in lower case) and within it the folder accounts and place your .csv file
there. Remember that folders are case sensitive so the folder must be identically named and use the
correct capitalization.

Now your module is ready to be packaged. Execute the ant task package.module

-Dmodule="yourModuleJavaPackage" and it will create an .obx file that is ready to be published or
distributed.

Chart of Accounts are always at Client/Organization level so nothing happens when you install this type
of modules but just that the chart of accounts is available to be applied to new clients (during Initial
Organization Setup), new organizations (during Initial Organization Setup) or to existing
Client/Organizations (by Enterprise Module management).

Standard Reference Data

You can also include any other data in your module through standard reference data using data sets.

First you need to create in your instance the data you want to include. It could be taxes for a particular
country, product categories or a collection of alerts for a particular industry or any other data. You can
combine different data from different tables in your module.

After that, the next step is to create a module and mark as checked the Has reference data property.
Keep unchecked the other properties related to reference data (Translation required, Is translation
module and Has chart of accounts). Complete the Reference data description with information about the
data you are including (this description might be different from the module descriptions since the
module might include some other content). This module does not need any Includes, Data packages and
DB prefix and will depend on the module versions that define the data structure you aim to include (eg.
if your data comes from table defined in core 2.50.1234 then it will only depend on this module-
version).

Then you have to create within your module as many data sets as you need to define your data. A data
set is a collection of data defined by the tables where those data are stored, the rows included -defined
through a filter clause for each table- and the columns you want to include for each table. Data sets
support advanced data definition to include full business objects (eg. when including an invoice you
might ask the system to include all its members -lines, taxes, etc.- as well). Click here for a general
description of datasets.

You can create datasets in the Data Set Window within the Application Dictionary menu folder.

There are some details you need to be aware when creating data sets:

 Of course the data set should be assigned to your module in which you will distribute those data
 Data access level is related to data access level in AD tables, read here for more details. It
defines the level at those data will be imported -of course it will be restricted to the levels
allowed by the table where data is stored- and when data is imported in the instance that
installs the module:
o System only: it will be imported at System level at installation time. Only tables
with System only, System/client and All data access level are allowed in System
only data sets (eg. Roles, Alert rules, etc.)
o System/client: it will be imported at Client level during "Initial Client Setup" or
"Enterprise module management" processes. Only tables
with System/client,Client/Organization and All data access level are allowed
in System/client data sets (eg. Roles, Product categories, etc.)
o Client/organization: it will be imported at Client or Organization level during "Initial
Client Setup", "Initial Organization Setup" or "Enterprise module management"
processes. Only tables with Client/Organization and Organization data access level are
allowed in Client/Organization data sets (eg. Product categories, Business partners,
etc.)
o Organization: it will be imported at Organization level during "Initial Organization
Setup" or "Enterprise module management" processes. Only tables
withClient/Organization, Organization and All data access level are allowed
in Organization data sets (eg. Business partners, Sales orders, etc.)
 Check the Export allowed field to show the Export Reference Data button. From this button you
will be able to export your data to xml files and this way include them in your .obx file

Next step is to define the collection of tables included in your data set.
Again some details you need to be aware:

 You can add as many tables as you need in your data set
 For each table you can add a SQL where clause to filter data in the table. In the example above
it is filtering by Product categories in a particular client. Click here for more information on the
DatasetTable where clauses.
 You can include all columns in the table or declare one by one the ones you want to include
 Tipically you will not want to include audit info in your data, you can exclude audit info columns
 By default your data set includes just the records in the data set tables matching the SQL where
clause criteria. But you can define the table in your data set as "Is business object". If you do it
then the system will export not only the records in the table matching you SQL where clause but
recursively any other record in the system that has a foreing key to these records and that is
defined as member of the referenced record (business object) through the
[ERP/2.50/Developers_Guide/Database_Model/org.openbravo.model.ad.datamodel/AD_Column
#Link_to_Parent_Column | "Is parent"]] attribute in AD column.

Take into account that the system will export not only the data defined by you data set but also any
information referenced by it. This way it is guaranteed that the system will be able to import that data in
any other instance although the referenced data does not exist there. If it is the case the import process
will also import any referenced data needed to complete the operation.

Now you have to define the columns included for each table.
Usually there is no need to define columns in your table since tipically you want to include all of them
but audit info and you can do it in the table itself as described before. Some times you might want to
exclude some other columns by checking the Excluded field.

Once you have completed the definition of all your data sets you have to export them to xml files so
they are included in your .obx file when packaging your module. To do that you have to click on
the Export Reference Data button in the data set header. It will create a xml file named as the data set
in referencedata/standard subfolder within your module folder. Of course you can run this process as
many times as you need to fine tune your data. Finally package it as usual by executing the ant
task package.module -Dmodule="yourModuleJavaPackage" that will create an .obx file that is ready to
be published or distributed.

As described before you can also publish new versions of your reference data modules. Take into
account that to ensure data consistency reference data is not deleted from the instance when applying
an update/upgrade where the new data set does not include some records originally included. So instead
of remove them from the data set you should inactivate them.

Module Scripts and Build Validations

It is possible that your module needs to check if the system complies with some specific rule before
installing it. If this is the case, a Build Validation can be used to verify it. A Build Validation is basically a
process, defined as a Java class, which can connect to the database and to the Openbravo sources,
check whatever the developer wants, and finally return a result of the validation. If the result is not
positive, the module is not applied in the system.

Also, it is possible that your module needs to do specific transformations to the system while installing.
This changes can be of basically any kind, such as modifying some data in the system, or adding some
database object which uses some Oracle or PostgreSQL specific syntax which makes it not possible to
add it through our standard dbsourcemanager+xml files. For this, you can use Module Scripts, which like
Build Validations, are defined as a Java class which can connect to the database, and do any kind of
modifications to client data.

If you want to know more about how to create Build Validations and Module Scripts, you can check this
link. If you plan to use a module script to create a database object which uses some kind of database
specific syntax or feature, you should exclude it from the dbsourcemanager standard model. To learn
how to do this, read this document

Configuration Script
Up to know we have seen how to extend Openbravo through modules. As you remember modules are
able to add new artifacts -application dictionary components, software resources and reference data- but
are not allowed to modify other modueles to avoid crossed dependencies between them.
But there is a special type of modules -Industry Templates- that can include changes to other modules
within it. It is done through configuration scripts. A configuration script is a collection of changes that
your Industry Template does in other modules included in the Industry Template.

Create a configuration script is straightforward. You don't need to manually edit it but the system will
generate it automatically as you go. You only need to create an Industry Template in your instance. You
can only have one Industry Template "in development" at a time and any change you do will be included
in the configuration script of that Industry Template.

If you want to know more about how to create Industry Templates and configuration scripts, you can
check out this document.

Development tasks
All development tasks have been reorganized in Openbravo 2.50 and modules are properly managed so
you can update your database or compile your system taking into account only changes in a given
module. Read this document to get a complete explanation of all available development tasks.

Publish the .obx file of a Module

Once you have finished developing your .obx file, you can publish it to the central repository.

1. Package your module using the following ant command, where yourModuleJavaPackage is the
java package you defined in your module:

ant package.module -Dmodule=yourModulePackage

2. Follow the steps defined in Publish Version document.

Advanced concepts
This section explains in detail some advanced concepts of Openbravo Modularity. It is not strictly
necessary you to read all these details but it is worth to do it, it will help to avoid mistakes when
creating your modules.

Version numbers and how dependencies and includes are managed

Different releases of an Openbravo module are identified with a version number. An Openbravo Version
Number is an string up to 10 characters lenght following the format x.y.z where:

 x is a number indicating module generation (eg. very relevant changes in functionality, user
interface or technology)
 y is a number indicating major release (eg. new features available in a regular basis)
 z is a number indicating minor release, usually matching the SCM (subversion, mercurial, etc.)
revision number. Minor releases should not add any new functionality but just fix bugs within its
major release with the objective of increasing stability

A major release is identified by the two first digits (x and y). For example, core 2.50.3642 and core
2.50.3921 are two different minor versions within the core 2.50 major version.

Modules have to declare any dependencies between them and all of them must depend finally on core
module. Dependencies are declared to a particular major version of a module or a range of major
versions, starting from a concrete minor version. For example, module A depends on core 2.50 or
module B depends on any version of module A from version 1.0 to version 1.6. In a similar way Packs
and Industry Templates declare the modules (including other packs and Industry Templates) that are
included within them. In this case ranges are not supported, just a major version of a module can be
included in a Pack/Industry Template. Be aware that both dependencies and includes use a full version
number (x.y.z) to identify the version, minor version is taken into account to define the starting version
of the dependency, but it is not for the to version field. In this case, the minor version (.z) is used just
for keeping track of the actual release that was used when the module was developed.

Usually a major release matures in a process through three phases of increasing stability: alpha, beta
and production. Many minor versions can be published in each phase but the release can not be
considered stable enough to build something on top of it till the beta phase is reached. You should not
develop a module that depends on an alpha version of other module to avoid instabilities inherent to this
stage.

To improve maintainability minor versions of modules are not taken into account when managing
dependencies. It means that in the previous example module A should be compatible with any minor
version of core 2.50. It causes some limitations on what developers can do when working on a minor
version but highly improves maintainability by minimizing the effort of checking dependencies. You only
need to review if your module remains compatible with a module it depends on when a major version of
that module is released.

To enforce this behavior it is of paramount importance to clearly state what changes are forbidden within
a minor version and to enforce them before publishing. The general rule is that the public API of the
module should not change, and it can be expressed in more detail with the following set of not allowed
changes within a minor version:

 Data model
o Add a mandatory column in a table. New nullable columns are allowed while the
business logic support null values properly
o Change the datatype or reduce length/precision in a column
o Remove a column
o Renaming a column: it is equivalent to remove and create that column
o Add a new constraint to a table that was not previously enforced by the application.
Constraints to avoid wrong behavior are allowed but should be warned
 Business logic
o Changes in the signature of public methods/procedures/webServices: method name,
number and type of parameters, return type and thrown exceptions
o Changes on expected functional behavior (eg. meaning of a particular column/attribute,
etc.)
 Navigation
o Changes in the URL's for direct navigation to web components (windows, reports, etc.)

These restrictions make the fixing bugs exercise more difficult but are a key factor to create a
maintainable ecosystem. They should be guaranteed during the beta and production phase of any
release of any module. During the alpha phase -when bug fixing activity is high- you could break this
rule to get some flexibility and taking into account that there should not be any other module depending
on it.

Dependency types
   The contents of this section are available from 2.50MP21

Dependency type is defined by the Dependency Enforcement field, the possible values it can take are:

 Major Version: This is the default enforcement and works as described above (it is the
behavior all dependencies had in releases previous to 2.50MP21.
o First Version is the first minor version the dependency is compatible with. So if first
version is 1.1.5, it will be compatible with all the 1.1.x minor versions starting from
1.1.5, but not with any other major version such as 1.2.0, unless Last Version is
defined.
o In case Last Version is defined, it is only taken into account if it is a different major
version than the first version, in this case it defines the latest compatible major version,
 but its minor version is not taken into account. For example if the dependency is
defined from 1.1.5 to 1.3.6, the module will be compatible with all 1.1.x starting from
1.1.5, with any 1.2.y version and with any 1.3.z (including minor versions of 1.3 higher
than 1.3.6).
o If Last Version is blank or it is within the same major version First Version is in, the
compatibility is defined for all versions in the same major version First Version is in
starting from the minor version First Version defines.
 Minor Version: In case both First Version and Last Version are defined, the compatibility is
from the minor version in First Version to the minor version in Last Version(even they belong to
the same major version). If Last Version is blank, the only compatible version will be the one
defined by the First Version.
 None: There is no restriction between major versions, First Version defines the first compatible
minor version and the compatibility is for all versions higher than this one including major
versions.

User Editable Enforcement

Module owner can define whether the enforcement is overwriteable by user. By default it is not and
instances prior to 2.50MP21 cannot overwrite it.

In case it is possible to overwrite the module dependency's enforcement, user will be able to set a
different enforcement for this dependency in his instance being this value the used to calculate
dependencies.

Users can select the enforcement for User Editable Enforcement dependencies from the Settings tab
in Module Management window.

Model - Implementation concept

AD_Model_Object is a table in Openbravo Application Dictionary to link Application Dictionary
components and the class (servlet) that implement that object. So this table is a mapping between the
logical side (AD components) and the physical side (classes). It is useful for two main reasons:

1. It allows to implement in a generic way rules that apply to all AD components like security,
navigation and others.
2. It is the mechanism to automatically populate the web.xml file where classes (servlets) are
declared. The AD_Model_Object_Mapping is an utility to create the mapping entries in the
web.xml file.

There is a few number of exceptions to this description: some servlets that are deployed in Openbravo
context but are not linked to any AD component, such us the DataGrid or the AuditInfo servlets. They
are invoked from manual or standard components (windows, forms, etc.) through http requests by
hardcoding its url-mapping in the request. It can be interpreted still as a mapping of actual classes that
implement a functionality that is not described in current Openbravo model, although it may be in the
future.

Modularity project aims to allow through modules the deployment any type of optional content in an
Openbravo instance, including additional entries in the web.xml file of openbravo context. It is done
through the AD_Model_Object table. Developers can create entries in this window not linked to any AD
component. To support any type of web.xml content (servlet, listeners, filters, etc.) a new column is
added to the AD_Model_Object to represent the type of web.xml entry that the developer is adding.
They can also declare a set of mappings for the entry and a set of parameters if needed.

The module of a AD_Model_Object entry is calculated with the following rule: if it is linked to any AD
component then the module is the one assigned to that AD component, otherwise the module is the one
assigned to the AD_Model_Object record itself.

With this extension the web.xml file in the openbravo context will be fully extensible through modules.

Example on how to create and package your module

Now it is time to go practice. You can follow this howto that will guide you step by step on how to create
and package your first module.