ERP 2.50:Developers Guide/Concepts/Publishing Modules
This document explains how to publish and manage modules in Central Repository to make them available to any Openbravo ERP instance.
The Central Repository is a system embedded in the Openbravo Forge to provide services related to Openbravo ERP Modules for developers and users:
- For developers:
- Register a module: a developer registers a new module in the Central Repository to get global unique identifiers to be used for development (it's highly recommended to register a module before starting the module's development).
- Publish a new version of a module: a module can have different versions in its life cycle. For each of them module owners need to update the information in the Central Repository to make this new version available for users.
- Manage life cycle of a version: a module version can be in different statuses during its life cycle, each of these statuses makes it available to different kinds of Openbravo ERP instances.
- For users:
- Search for modules: from the MMC users can query the Central Repository to get a list of modules that match with user request.
- Scan for updates of a list of module versions: from the MMC users can request to the Central Repository if there are available updates (newer versions) for all the modules installed in their instances (or just for one of them).
- Get the code of a module version (to be installed): for both installing new modules and updating current ones it's needed to get the compressed file (.obx file) that stores module code.
This section explains the complete life cycle of a module starting from its creation.
There are two properties in the modules that are very important to be unique and no other module has the same value for them. They are Java Package and DB_Prefix. If more than one module with the same Java Package or DB_Prefix is tried to be installed in the same Openbravo ERP instance there would be conflicts between them that would prevent the correct installation. This is why it is very important to guarantee uniqueness for these properties.
The way to guarantee this uniqueness worldwide is to register modules in Central Repository just after their creation. In this way you will notice in case other registered module is making use of the same Java Package or DB_Prefix you want to use and in this, case you will be prompted to change your initial election. It is important to register new modules just after their creation before starting their development, doing so you will notice possible conflicts in Java Package or DB_Prefix that would affect your module's artifacts' names and would require a lot of work to change if it was registered after they were developed.
You can register your module through the Register Module button in the main tab of the Module window. It sends your module's information to Central Repository, checks Java Package and DB_Prefix are not already registered by any other module and reserves them for yours making not possible other modules to use them. In case they are already used, an the process is aborted and an error message is shown you to change them before trying to register again.
A registered module is not publicly available for download, so even if you don't plan to publish your module it is recommended to register it just to prevent other registered modules to use the same Java Package or DB_Prefix you took for yours.
After registering a module it is possible to unregister it in case it has not been already associated with any project, see Unregister Module section.
Associate with a Forge Project
If the module is wanted to be publicly published in Central Repository to be accessible through the Module Manager Console, it is necessary to associate it with a Forge Project.
The first step to do so is to create a new project in the Openbravo Forge. This can be accomplished by:
Click on the Create a new project button which can be found in the left menu in the forge.
Associate Project with your Module
Once there is a project registered in the forge, the next step is to associate the module you already registered with it.
Go to My Profile by clicking the link in the Toolbox in the left menu. There you can find My Modules section, where all the modules you are admin for are listed. Among them, you'll find the one you just registered.
If you click in the module name, a new window will be open where you can pick the project you want to associate your module with.
Note that the relationship module:project is 1:1, so each module can only be associated with a project and vice versa.
It is possible to unregister a module that has not been already associated with any project. This can be done from My Modules section (see above), by clicking the red cross next to the project name.
Unregistering a module will release the Java Package and DB_Prefix that module has making them available again.
Version Life Cycle
When a module version is completed and packaged it can be published in Central Repository.
- Access to the module you want to publish the version for.
- Click on Publish Version tab.
- Select the obx file with the version to publish.
- Select the initial maturity status for that version. Maturity statuses are detailed in Version Life Cycle section.
Version Life Cycle
During the life of a module, it can be at different maturity statuses in Central Repository. The maturity status for a version should be promoted after passing some tests and/or being used for some time in a real production instance. Setting the maturity for a version is up to the module administrator.
The possible values version maturity status can have are:
- Test: This status is intended to be used for versions that have not been completely tested. A version published with this status should be installed only in instances which desire to test it, generally to provide feedback to the module administrator/owner. Versions with this maturity shouldn't be installed in production environments. Not recommended for production purposes.
- Controlled Release: This second stage is for versions that have been deeply tested and it is ready for production. The module owner feels confident with it, but he wants to have some maturity period before he tags it as General availability. It will become available for the instances of this module early adopters, where it can be installed for production. Recommended for production purposes to early adopters.
- General availability: It is the final stage for a version. It is supposed to have passed the two previous ones, so it is tested and it has been working during some time in production instances. It is available for every instance and can be safely installed for production. Recommended for production purposes to all users.
- Canceled: Canceled versions are not available to be installed in any instance.
Setting Module Version Maturity
Maturity level for a version is set by the module owner. He should define and follow some rules to decide which is the correct status for each version of his modules, but finally is up to him to set it.
When publishing a new version in Central Repository, the module administrator will be prompted to select the initial maturity status for that new version. Being Test the default value.
Note that the status for a version can always be upgraded but it cannot be downgraded.
At any point of time, the module administrator can promote the maturity of a version.
The steps to do it are:
- Select in the forge the module that contains the version to promote.
- In List Version tab, click on the version to promote.
- Go to Version Status tab. There it is shown the current status and a drop down list to select the new one. This list will not be shown for General availability versions, since they cannot be promoted. Select the new status and click on Update Status button.
In case in a published version a critical issue is found and the module owner wants to prevent this version to be installed in more instances, he can cancel it.
Once a version is canceled it will not appear to be installed or upgraded in any instance. Note that instances that have already installed it, this version will still be usable.
The steps to cancel a version are the same as the ones to promote its status, but in last step click on the Cancel Version button instead of on the Update Status one.
Allowed Maturity Status in Openbravo ERP
Minimum maturity status accepted in Openbrravo ERP instances can be configured. Detailed explanation about how to do that can be found in Modules Management Configuration Manual.
Module versions can be defined as commercial. Doing so, they will be installable only in those Professional Subscription instances that have acquired previously the module.
More information about selling modules can be found in the forge help.