View source | Discuss this page | Page history | Printable version   

How to create a Regions Module


About this document

This document is part of the Localization Guide for Openbravo and describes the process of creating a module that includes the list of regions for a country.

Recommended articles

Before reading this howto, it is important to have a clear understanding about the Modularity Concepts, specially the process of creating and packing modules.

The main objective of a regions module is to provide a dataset with the list of regions for a concrete country. In case you haven't created yet a dataset, it is recommended to firstly read the How to create a Dataset article to get a general idea before moving to the particular scenario about regions.

From the functional side there is no special knowledge required, it is only recommended to read the Country and Region article.

Estimated effort

A regions module is probably the easiest module in a localization project. The final effort highly depends on the number of regions to be included into the module. In general the estimated duration for creating a regions module should be just a few hours.


The list of countries is embedded in the Core module as part of what it is called Masterdata (which also includes, for example, currencies). However regions are not included and must be created for every country, making it a perfect candidate for a localization module.

A regions module just consists on a dataset with the list of regions for a particular country. When a user installs this module, his instance will automatically contain the regions for that country.

Apart from the evident benefit of making it faster for the user to define addresses, the regions module will be the base for developing new modules that depend on this regions definition, like the Taxes module, which may include different taxes settings based on these regions.

Register the regions

To define the regions for a country it is necessary to go to the Country and Region window and select the country. If your country is not listed in this window, please report an immediate issue and we will include it in the next MP.

Inside the Region tab you must enter the regions for that country:

LocGuide Regions 10.png

Finally, in the country definition we should specify that this country has regions and set the name regions receive in the country's language. For example, in Spain a region is called Provincia

LocGuide Regions 20.png

Module definition

As you already know, the regions module is like any other module that includes a dataset, so there are no special tricks for declaring it inside the Application Dictionary, but just some few considerations:

LocGuide Regions 30.png

Dataset definition

Dataset definition is the key step in this process. A wrong dataset definition can waste all our previous work, so it is important to follow all these considerations:

LocGuide Regions 40.png

The dataset definition is ready, so we just need to export it to a file pressing the Export Reference Data button. This process queries the previous tables and gets all the records that fulfill the HQL/SQL Where clause, generating a XML file inside the module's referencedata/standard directory. As a fast check, you can open this file using any plain text editor and you can verify that it contains several lines.

In case the file is empty, you should double check the dataset definition, specially the HQL/SQL Where clause used for each table.

Packaging the module

To generate the obx file we should follow the standard steps from the command line:

ant export.database
ant package.module -Dmodule=<regions module java package>

Testing the module

To properly test this module, we must to install it in a fresh Openbravo instance. The installation process will automatically insert all the regions for the country, because the dataset has defined at System level.

After a successfully installation, we just need to check all the regions for our country has been inserted.

LocGuide Regions 10.png

Considerations when releasing new versions

If you plan to release new versions of the regions module, you must remember some important aspects related to the common behaviour of datasets.

The considerations explained on the How to create a Taxes module article can be directly extrapolated to this module, so please read this chapter before start working on the new version.

Retrieved from ""

This page has been accessed 6,420 times. This page was last modified on 18 June 2012, at 08:48. Content is available under Creative Commons Attribution-ShareAlike 2.5 Spain License.