Chapter Week1

59
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.

Transcript of Chapter Week1

Page 1: Chapter Week1

Openbravo ERP Advanced Development

Chapter 2 – Setupv2.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!

Page 2: Chapter Week1

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_Installation/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 necessary2. simply press the Open My Virtual Machine button on the front page of the

course

Page 3: Chapter Week1

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 [email protected]

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:

Page 4: Chapter Week1

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

Page 5: Chapter Week1

manager interface:

Windows + Bitvise Tunellier

After installing Bitvise Tunnelier, run it to receive the front screen where connection parameter can already be entered:

Page 6: Chapter Week1

Before connection, check the Options tab and see the On Login section, Open Terminal and Open SFTP should be checked off.

Page 7: Chapter Week1

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:

Page 8: Chapter Week1

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

Page 9: Chapter Week1

# 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 guesto First nameo Last nameo Business Partner - link to an existing Business Partner to whom the

invoice will be issuedo Guest Rate - daily rate the guest is entitled to (fixed list of options: A, B or

C) Room

o Numbero ARate - rate for regular guests that have stayed for more than 10 nights

within the last 6 monthso BRate - rate for guests that have stayed for more than 5 nights within the

last 6 monthso CRate - default rate for a walk-in guesto Type - Single/Double/Suiteo Smoking - Y/N

Stay - an overnight stay of a particular guest in a roomo Date In - date of the check-ino Planned Nights - preplanned booking of a number of nightso Date Out - date of the check-outo 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

Page 10: Chapter Week1

Window Functionality

To support the functionality indicated by the structures above, we will require two windows:

Guest/Stayo 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 monthso 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:

Page 11: Chapter Week1

o [Withholding]o [Product Template]o [Volume Discount]o [Shipment Route]

Within the main [Business Partner], hide these fields:o Summary Levelo Expected Lifetime Revenueso Shareo Volume of Saleso 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:

Page 12: Chapter Week1

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.

Page 13: Chapter Week1

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.yourPackage.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.

Page 14: Chapter Week1

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.

Page 15: Chapter Week1

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):

Page 16: Chapter Week1

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.

Page 17: Chapter Week1

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.howtosBuildfile: 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 SUCCESSFULTotal 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

Page 18: Chapter Week1

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

Page 19: Chapter Week1

http://wiki.openbravo.com/wiki/ERP/2.50/Developers_Guide/ How_to_define_users_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:

Page 20: Chapter Week1

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:

Page 21: Chapter Week1

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_package_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.

Page 22: Chapter Week1

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:

Page 23: Chapter Week1

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]:

Page 24: Chapter Week1

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:

Page 25: Chapter Week1

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:

Page 26: Chapter Week1

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:

Page 27: Chapter Week1

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:

Page 28: Chapter Week1

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

Page 29: Chapter Week1

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:

Page 30: Chapter Week1

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:

Page 31: Chapter Week1

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

Page 32: Chapter Week1

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

Page 33: Chapter Week1

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.

Page 34: Chapter Week1

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.

Page 36: Chapter Week1

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

Page 37: Chapter Week1

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

Page 38: Chapter Week1

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

Page 39: Chapter Week1

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

Page 40: Chapter Week1

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

Page 41: Chapter Week1

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.

Page 42: Chapter Week1

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

Page 43: Chapter Week1

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

Page 44: Chapter Week1

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.

Page 45: Chapter Week1

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

Page 46: Chapter Week1

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.

Page 47: Chapter Week1

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.

Page 48: Chapter Week1

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

Page 49: Chapter Week1

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

Page 50: Chapter Week1

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

Page 51: Chapter Week1

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.

Page 52: Chapter Week1

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.

Page 53: Chapter Week1

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.

Page 54: Chapter Week1

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

Page 55: Chapter Week1

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 modelo Add a mandatory column in a table. New nullable columns are allowed while the

business logic support null values properlyo Change the datatype or reduce length/precision in a columno Remove a columno Renaming a column: it is equivalent to remove and create that columno 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 exceptionso 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

Page 56: Chapter Week1

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.

Page 57: Chapter Week1