Modularity Concepts

Languages:

English| | Translate this article...

Back to Main Page

Modularity Concepts

This document contains an overview of the process of developing InfiniteERP Modules. It describes the concepts, artifacts and processes involved in building, packaging and distributing modules for InfiniteERP.

Overview

InfiniteERP supports the 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 InfiniteERP. Examples of modules are: additional reports, additional windows, connectors, content packs (translations, chart of accounts, list of tax codes, product categories, etc).

The objectives of modularity are:

• Making it easier to contribute to InfiniteERP 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
• Shortening the implementation cycles by enabling system integrators to develop micro-vertical templates

Concepts

Before you start, it is required to understand some concepts. These concepts are described in detail in the following sections.

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 InfiniteERP. In a Module, you cannot modify elements of other modules — including core. The reason for that is to avoid cross-dependencies between them.
• Bundle: a Bundle is a collection of modules and no more. They are intended to simplify deployment and to encourage fine-grained modules. Special bundles are localization and verticalization bundles.
• Templates: a combination of a Module and a Configuration Script that is able to modify the behavior of AD components in Modules.

The three of them are generically referred to as Modules.

Artifacts in an Extension Module

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

• Application Dictionary Components: Metadata that describes InfiniteERP such as Windows, Tabs, Fields, Messages, etc.
• Software Resources: InfiniteERP components not expressed as metadata such as `XML` definition of database schema objects, Java classes, 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.

The InfiniteERP platform itself cannot 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.

Packaging and .zip and .jar Files

All the content of a module — code, utility files, data — is contained in a separate folder for each module. All the content in that folder is related to, and only related to, that module. There is a folder within the main InfiniteERP 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 Java package of the module. In that folder the source code structure of InfiniteERP (config, src, src-db, lib, etc.) is replicated as required to store the content of the module.

Modules are distributed as .zip or .jar files which are compressed files of the module folder.

InfiniteERP Repository

Supported InfiniteERP modules are published as packages. Licensed developers and partners with access can browse and download packages available there.

More information about module publishing can be found in How to Publish a Module.

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 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 the following sections each type of artifact is described in detail.

Step 1 is common to all types of modules. Step 2 depends on the requirements of your module. It has not significantly changed from the way you have developed InfiniteERP code in previous releases.

Be aware that from now on every piece of InfiniteERP code belongs to a module (you can see, for example, that the InfiniteERP distribution in fact includes several modules, and one of them is Core). You should do all your new developments through modules, including your customizations. Still you can do changes directly in other modules — including InfiniteERP 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, as you can update individual modules without doing any changes to other ones (so, for example, you can update the InfiniteERP distribution modules without doing any changes to your modules).

Register a Module

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

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

• Each module has its own native (base) language. In the following sections the translation process is described; by now just choose the language you prefer to develop the UI of your module. Of course, if you choose English it will be easier to disseminate (e.g., to find people to translate it to other languages).
• Name, description and help are the properties used to explain in the 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 InfiniteERP 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).
• The Java package is a unique identifier of your module and has to match the Java packaging names rules as described in the Java specification. You need to carefully set this value because you are not allowed to change it once your module is published. 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 com.yourcompany.yourPackage, org.yourfoundation.yourPackage.yourSubpackage, etc. You should name your modules with a Java package which doesn't start by com.infiniteerp or org.openbravo, but with an identifier of you, your company, or the project you belong to.
• 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 chosen by default when developing. This is just a way to set a default value for the module when you edit the Application Dictionary.

It is recommended to restart the instance after changing the development status of a module in order to update the cache's status. Also note that production instances cannot have modules in "In development" status.

• Some modules will not have UI (e.g., 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.
• If your module has a Chart of Accounts, you have to check this flag to allow the System to use them during the Initial Client/Organization Setup processes.
• 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.
• 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.
• The author of the module will be shown to the User 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.

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 take into account dependencies and the result might be wrong if they are not declared when developing your module. Typically, a module will depend on User Interface Application and in turn, it has a dependency on InfiniteERP core and eventually on other modules.

There is no need to edit the Translation tab. It is a tool for translators.

If your Module includes a table in the Application Dictionary then you need to register one (or many) data packages in your Module. For a full description on how packages are used, visit 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 package, that has to match the Java packaging names rules. 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 string of up to seven characters. 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 the InfiniteERP 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, 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 if you don't plan to publish your module.

Naming

It is of paramount importance to use proper names for modules. Especially for Java Package and DB Prefix. This is the only warranty that there will not be conflicts when installing other modules.

Java Package

Java Package should be a valid unique Java Package. These are instructions from Java.sun.com:

You form a unique package name by first having (or belonging to an organization that has) an Internet domain name, such as sun.com. You then reverse this name, component by component, to obtain, in this example, com.sun, and use this as a prefix for your package names, using a convention developed within your organization to further administer package names.

Example:

If your company is named Foods & Beverages and you have an Internet domain called fandb.com, all your Java packages should start by com.fandb. If you create a CRM module, its Java package could be com.fandb.crm.

Note: Java packages starting by com.infiniteerp or org.openbravo should only be used by modules distributed by InfiniteERP.

DB Prefix

It is a good practice to use a short prefix for your company followed by a prefix for your module. Following the previous example, all your DB prefixes could start by FB, and the one for the CRM module could be FBCRM.

About customization modules: Usually customization modules are not intended to be published in a public repository. In this case, DBPrefix should start with CUST. Modules with these kinds of DBPrefixes cannot be registered in a public repository but are collision safe because no other module in a public repository can use this DBPrefix. This is an important decision to be taken before starting the module development: in case there is any chance of publishing the module at some moment, it should follow the standard rule; if it is absolutely sure that it will not be published you can use CUST.

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.

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

An AD component will only be editable when the module it belongs to is in development, or if there is an Industry Template in development in the system. If you change a property in an AD component that is not in development the system will raise an error to avoid you to perform unintended changes.

Translations are managed in a particular way and you don't need to care about translations when developing. 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.

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 data package in a module. It is needed by the DAL to properly manage packaging of generated entities and XML naming. Only packages of "in development" modules are available when you edit a table. The module of a table is the module of the package of a table.

Columns are assigned by default to the module of their table. But you might want to add in your module a column within a table in a different module (e.g., 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 (taking into account that the full column name must not be greater than 30 characters). EM stands for External Module. The same rule is applicable for the Name property which is used to generate DAL properties, therefore must be unique among different modules.

Windows, Tabs and Fields

Windows, Tabs and Fields follow the general rule. The three of them are linked to a module. By default, when you add a tab to a 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.

When editing the field sequence the system will guarantee that you do not change the sequence number of fields that are not in your module, so if you add a new field in a tab of another module the sequence number of the original fields will not be modified.

The tab class and mapping is automatically managed by the system and you do not need to take care about it.

Reference

There are four types of references: Data type, List validation, Search validation and Table validation. Only List validations and Table validations can be included in a module different to InfiniteERP core. Data types and Search validations will be supported in modules in future releases.

All the values included in a List validation are included in the module where the List validation is defined. You cannot 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 revise. 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 cannot include in your module a message with a numeric search key to be raised by a PL/SQL object through the RAISE_APPLICATION_ERROR function.

Text Interfaces

Text interfaces window usually is not edited manually but entries are automatically generated by the translation process when it parses files to be translated. This process takes into account the packaging of the file being translated and the text interface entry is properly assigned to the module. This process should be transparent for developers but you can browse the entries that your manual developments have created and edit them.

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 searches 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, Auxiliary 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.

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

Model - Implementation Mapping

Model - Implementation mapping is a generalization of the Model-Object concept that was present in previous releases. Through this new window you can include in your module the entries you need to add to the web.xml file of the InfiniteERP context.

Model - Implementation mappings follow the general rule. You can declare a new entry in your module by just creating a new record in the Model - Implementation mapping window and linking that entry to your module. All mappings and parameters assigned to it will be included in the module where the Model - Implementation mapping is declared.

Software Resources

To develop your module you may require to include some software resources. Software resources are InfiniteERP components not expressed as metadata such as XML definition of database schema objects, Java classes, JAR libraries, XML files, etc. All you need to add to your module has to be packaged within InfiniteERPMainFolder/modules/yourModuleJavaName. Within this folder, you have the standard InfiniteERP folders to hold your software resources (src, src-db, lib, etc).

The build process of InfiniteERP takes into account the source code structure that is split into modules. Be aware that this concept is completely different from the srcClient that was used in previous releases: you are not allowed to physically overwrite a file in the InfiniteERP 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 com.infiniteerp.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 InfiniteERP is as 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 InfiniteERP standards
• If the database schema object is mapped with any Application Dictionary (Tables & Columns, Reports & Processes) then the developer imports 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 — e.g., running the synchronize terminology process — and completes AD information to fully describe the solution she/he targets. It might require as well to create some InfiniteERP 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 exports 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 committing 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 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 know 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 (e.g., MYMOD_MYTABLE, MYMOD_MYPROCEDURE, etc.)
• Every object (tables, constraints, indexes, functions, triggers) needs to have a unique name in the database. To avoid any kind of duplication, constraint and index names in particular need to start with their table name. This ensures that there will be no name duplication in the whole database
• 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 + "_" (e.g., EM_MYMOD_MYCOLUMN, EM_MYMOD_MYCONSTRAINT, etc.). EM stands for External Module. So you can use standard column names in your tables (e.g., 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

Following this simple rule, you can include in your module as many database schema objects as you want. But be aware that you cannot modify database schema objects in other modules as it would break the main rule: "a module cannot 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.

Naming Exceptions: It is possible to define database schema objects within a module that do not follow the naming rules explained above. This is specially useful in order to move to modules existent InfiniteERP instances in older versions. It is important to note that this feature should not be used for new developments in general. If a module contains a naming exception, it will not be possible to publish it to a public repository, because it would not be possible to guarantee that the object defined as a naming exception would not collide with another object defined in a different module.

When a database schema object is defined as an exception for a module it is exported to that module instead of 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 the database, not in Application Dictionary

Extension Points: Extension Points allow the developer to attach execution code to predefined specific points inside InfiniteERP PL/SQL functions. This functionality can be used to extend the functionality of some Core functions, without overwriting them in any way. This way of extending the functionality fits very well with Modularity, as it allows extension but also keeps maintainability and upgradeability.

Java Classes, Other InfiniteERP MVC Objects and JAR Libraries

Java classes, other InfiniteERP MVC objects (HTML, XML and XSQL files) and JAR libraries follow the general rule to add software resources in your module. You have to package this code within the src folder located in your module folder.

When InfiniteERP builds the system it will dynamically 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/runtime folder inside your module, are added to the classpath at compilation time and finally deployed to the InfiniteERP context.

After the generation of code and compile process the build process deploys all the content to the InfiniteERP context in the servlet container. There are two modes of deployment — class and war — that are explained in Development Build Tasks.

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 the InfiniteERP context in a standard way so these resources can be accessed from the pages in your module by referencing them.

You can also reference other web static content resources included in core or other modules. In that case, remember to explicitly 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 the InfiniteERP context.

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

Reference Data

InfiniteERP 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 installation 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 (e.g., 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 its native language as the language you are going to translate to. 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 Java package — within the modules folder. 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. 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.

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

Chart of Accounts (CoA)

Typically you should add just one Chart of Accounts 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.

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. 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 Java package — within the modules folder. Within 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.

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. Complete the Reference data description with information about the data you are including. 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.

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.

You can create data sets in the Data Set window within the Application Dictionary menu folder.

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

• The data set should be assigned to your module in which you will distribute those data
• Data access level defines the level at which data will be imported and when:

 * System only: imported at System level at installation time. Only tables with System only, System/client and All data access level are allowed
 * System/client: 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
 * Client/organization: imported at Client or Organization level during Initial Client Setup, Initial Organization Setup or Enterprise module management processes
 * Organization: imported at Organization level during "Initial Organization Setup" or "Enterprise module management" processes

• Check the Export allowed field to show the Export Reference Data button. With this button, you will be able to export your data to XML files and this way include them in your .obx file

Next step is to define the collection of tables included in your data set.

Again some details you need to be aware:

• You can add as many tables as you need in your data set
• For each table you can add a SQL where clause to filter data in the table
• You can include all columns in the table or declare one by one the ones you want to include
• Typically 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 your SQL where clause but recursively any other record in the system that has a foreign key to these records

Now you have to define the columns included for each table.

Usually there is no need to define columns in your table since typically you want to include all of them but audit info. Sometimes 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 an XML file named as the data set in referencedata/standard subfolder within your module folder. 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.

Advanced Topics

There are special cases that must be taken into account when including tables and columns to reference data.

All columns in dataset are always reset, when updating reference data: In case you are developing a module that contains a dataset at a System/client, Client/Organization or Organization data access level, you must take into account that every time the user updates the reference data application (through Enterprise Module Management window) all the included columns will be updated. This is useful, but also a little bit dangerous.

What can be done in order to avoid this kind of issues? Just don't include that value in the dataset, and set it through the default value of the column.

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 InfiniteERP 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 the 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 How to Create Build Validations and Module Scripts. 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 How to Exclude Database Physical Objects From Model.

Configuration Script

Up to now we have seen how to extend InfiniteERP 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 modules to avoid cross-dependencies between them.

But there is a special type of modules — Industry Templates — that can include changes to other modules within it. It is done through configuration scripts. A configuration script is a collection of changes that your Industry Template does in other modules included in the Industry Template.

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

Development Tasks

See Development Build Tasks for a complete explanation of all available development tasks.

Advanced Concepts

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

Version Numbers and How Dependencies and Includes are Managed

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

• x is a number indicating module generation (e.g., very relevant changes in functionality, user interface or technology)
• y is a number indicating major release (e.g., new features available on a regular basis)
• z is a number indicating minor release. 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 3.0.13642 and core 3.0.13921 are two different minor versions within the core 3.0 major version.

Modules have to declare any dependencies between them and all of them must depend finally on the 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.

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 cannot be considered stable enough to build something on top of it until the beta phase is reached. You should not develop a module that depends on an alpha version of another 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 a module should be compatible with any minor version of the major version it depends on. It causes some limitations on what developers can do when working on a minor version but highly improves maintainability by minimizing the effort of checking dependencies. You only need to review if your module remains compatible with a module it depends on when a major version of that module is released.

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

• Data model

 * Add a mandatory column in a table without a default or onCreatedDefault. New not-nullable columns are allowed only if they have a corresponding default or onCreatedDefault value
 * Change the datatype or reduce length/precision in a column
 * Remove a column
 * Rename a column: it is equivalent to remove and create that column
 * Add a new constraint to a table that was not previously enforced by the application

• Business logic

 * Changes in the signature of public methods/procedures/webServices: method name, number and type of parameters, return type and thrown exceptions
 * Changes on expected functional behavior (e.g., meaning of a particular column/attribute, etc.)

• Navigation

 * 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

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

• Major Version: This is the default enforcement. First Version is the first minor version the dependency is compatible with. In case Last Version is defined, it defines the latest compatible major version. 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.
• 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.
• 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. This type should normally not be used.

User Editable Enforcement

Module owner can define whether the enforcement is overwriteable by user. By default it is not. 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.

Model - Implementation Concept

AD_Model_Object is a table in the InfiniteERP 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

There is a small number of exceptions to this description: some servlets that are deployed in the InfiniteERP context but are not linked to any AD component, such as the DataGrid or the AuditInfo servlets. They are invoked from manual or standard components (windows, forms, etc.) through HTTP requests by hardcoding their URL-mapping in the request.

By using modules, the deployment of any type of optional content in an InfiniteERP instance, including additional entries in the web.xml file of the InfiniteERP context, is allowed. This 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.

With this extension the web.xml file in the InfiniteERP context is extensible through modules.

Example on How to Create Your Module

Now it is time to go practice. See How to Create and Package a Module which guides you step by step on how to create your first module.

See Also

• How to Create and Package a Module
• How to Publish a Module
• Data Access Layer
• Application Dictionary
• Development Build Tasks

References

• Modularity Concepts — Etendo Documentation

---

This page is a derivative of Modularity Concepts by Openbravo Wiki, used under CC BY-SA 2.5 ES. This work is licensed under CC BY-SA 2.5.