Install Modules in Etendo Classic
Overview
This guide explains two different ways to install modules in Etendo Classic:
-
Gradle Standard Installation: This method involves manually defining the dependencies in the project's
build.gradle
file, specifying the modules to be included either as JAR or Source format. -
Using the Dependency Manager: A module pre-installed in Etendo instances that allows managing and installing dependencies directly from the Etendo Classic user interface, without the need to manually edit configuration files.
Important Notice
It is strongly recommended to choose only one method for managing dependencies: either Gradle Standard Installation or the Dependency Manager. Once you start using the Dependency Manager, it takes precedence over the build.gradle
file, and dependency information will be managed through the database instead. Combining both methods is not supported and may result in unexpected behavior or inconsistencies during the installation or upgrade of modules.
Authentication
It is important to mention that the dependencies are resolved from GitHub, so you must have the credentials properly configured as explained in the Use of Repositories in Etendo. Depending on the level of access your GitHub user has, you have access to public or private (commercial) packages.
Info
Along your license, you have access to all packages distributed by Etendo.
Gradle Standard Installation
Checklist
Set up credentials.
Search for modules or bundles to install.
Choose module format (Source or JAR).
Set dependencies in the build.gradle
file.
Expand Sources Code or resolve dynamic dependencies (JAR).
Install modules.
Restart Tomcat service and verify installation.
Search for Dependencies
There are two options to search and install modules in Etendo Classic. Choose one of the following:
You can install modules from the Etendo Marketplace, which contains packages grouped by functionality.
Steps to follow:
- Open Etendo Marketplace.
- Search for the module or bundle you want to install.
- Select it to see details and instructions.
- Choose the Etendo Classic Version, to determine the compatibility range of the dependency.
- Copy the installation line in your preferred format: Source Code (allows customizations) or JAR (precompiled).
Info
By selecting the Etendo Classic Version, the compatibility range is determined, which guarantees to always resolve to the latest version available for that Etendo version.
Tip
In addition, in each bundle you will find a link to the release notes with more information about each version, compatibilities and more.
Tip
If your Etendo Classic instance predates the supported versions, you must select version 24.x
Not Recommended
Avoid using the latest.release
version as it may not be compatible with your current Etendo version.
If you want to install specific modules directly from GitHub:
Steps to follow:
- Visit the packages section on Etendo Software GitHub or search within your own repository.
- Select the required module to get the necessary information.
- Copy the module information to include it in your
build.gradle
file.
For example, to install the Banking Pool module, copy the provided information there.
Set Dependencies in Etendo Classic
Based on the modules format you want to work with:
- In the Etendo project, open the
build.gradle
file. - In the dependencies area, paste the modules or bundle to install.
If you want to work with source modules, declare your dependencies using the moduleDeps configuration (notice the @zip extension).
E.g:
If you want to work with JARs modules, declare your dependencies using the implementation configuration.
E.g:Info
- You can declare a specific version (e.g. '1.0.0') or an interval of versions:
- [begin, end] Both versions are included
- (begin, end) Both versions are not included
- [begin, ) From a base version to the latest one
- And any other possible combination.
Gradle Exclusion Rules
You can make use of Gradle exclusion rules to prevent downloading a specific transitive module. Refer to Gradle Documentation
Resolve Dependencies
To work with source code, you must expand manually the modules using a Gradle task.
This task will try to download or update the modules declared as moduleDeps in the build.gradle
file.
A menu is displayed showing the modules that will be expanded, you have to confirm manually to continue with the expansion.
Tip
Only the main dependency defined in Source Code (moduleDeps) format will be expanded. If you want all transitive dependencies to also be resolved in this format, set the supportJars
property to false
in the build.gradle
file:
To work with JAR modules, you need to resolve the dependencies explicitly by running the dependencies
task, which displays the resolved dependency tree:
However, note that when executing any Gradle task, the JAR dependencies (declared with implementation
) are dynamically resolved beforehand.
When a new Etendo JAR dependency is added or its version is updated, it is necessary to run update.database before executing any compilation task (e.g., smartbuild
, compile.complete
, etc.).
Tip
You can force the compilation tasks adding to the Etendo extension the ignore flag
Or run the tasks with the -PignoreConsistency=true
flag.
Install Dependencies
Finally, update the database and compile the new modules.
Restart the Tomcat
Restart the Tomcat server and check the installation.
The module is ready to use in Etendo!
Dependency Manager
Javapackage: com.etendoerp.dependencymanager
- With this module, the user can access from the Etendo Classic interface all Etendo packages published in Etendo Software repositories.
- In addition, from the Module Management window you can query packages, available versions, dependencies and install new packages.
- Then, from the Dependency Management window you can update, remove and change the format of already installed modules.
Installation
The Dependency Manager is distributed by default in the current versions of Etendo Classic, in case it is not installed in your instance you can do it by following the Gradle Standard Installation section described above.
Tip
You can find the module in the Etendo Marketplace at the following link: Dependency Manager - Marketplace
Warning
You must make sure to use Etendo Gradle Plugin in version 1.5.1
or higher, check the plugins section in the build.gradle
file. For more information about plugin releases see, Etendo Gradle Plugin - Release Notes
Module Management Windows
Application
> Etendo Dependencies Management
> Module Management
Logged as System Administrator role, in the Module Management
window, the user can see all the modules to be added and select the corresponding version in the versions tab. Once one of the versions is selected, the dependencies of such version can be found in the dependencies subtab.
Info
The fields in this window are read-only.
Fields to note:
- Active: Checkbox to select if this module is active or not.
- Group: the identifier of the artifact.
- Artifact: the unit of deployment fetched and used.
- Installed Version: the version of the module if it is installed.
- Is bundle: Field to filter if this module is a bundle or not.
This window presents two buttons that can be used: Add dependency and Update Packages.
Buttons
Add Dependency Button
This button allows you to add the dependencies associated with a specific version of the selected module. When clicked, a pop-up window will display all the dependencies and modules that will be installed.
-
If a package bundle is selected: you will have the option to add all the modules within the bundle or select only the ones you need. Below, a new read-only grid will appear, showing the dependencies of the selected modules. This grid is for informational purposes, allowing you to see which dependencies will be added.
-
If a non-bundle package is selected: the grid will be read-only, displaying only the necessary dependencies for the module to work correctly. If no dependencies are displayed, it means that the module has no additional dependencies.
Warning
A warning notification is shown to inform the user about versions compatibility before installing the dependencies shown.
Info
Consider that by default, all dependencies are added in Source format.
Once the process is done, the Dependency Management window is opened and all the installed dependencies are shown.
Dependency Version Handling Rules
-
If the dependency version is greater than the installed version::
- No installed module and no record in
Dependency Management
window: New dependency record added. - No installed module but record exists in
Dependency Management
window: Update the existing record version. - Installed module and the dependency record exists in
Dependency Management
window: Update the existing record version. - Installed module but no dependency record exists in
Dependency Management
window: The local dependency is deleted, and a new record is added inDependency Management
.
- No installed module and no record in
-
If the dependency version is less than the installed version:
- Display error and disable the process, preventing installation of an older version to avoid compatibility issues. This approach ensures that dependencies are handled properly, maintaining compatibility and minimizing the risk of functionality loss. In case you need to install the dependency version anyway, you must downgrade the version from the
Dependency Management
window with the change version button.
- Display error and disable the process, preventing installation of an older version to avoid compatibility issues. This approach ensures that dependencies are handled properly, maintaining compatibility and minimizing the risk of functionality loss. In case you need to install the dependency version anyway, you must downgrade the version from the
Update Packages Button
This button is used to execute the Update Packages process which updates the list of available packages with the latest information.
Dependency Management Windows
Application
> Etendo Dependencies Management
> Dependency Management
Logged as System Administrator role, in the Dependency Management
window, the user can find all the dependencies installed in the previous step.
Fields to note:
- Active: Checkbox to select if this dependency is active or not.
- Group: The identifier of the artifact.
- Artifact: The unit of deployment fetched and used.
- Version: Version of the module
- Format: Describes the dependency format. They can be
Source
,JAR
orlocal
.Source
: In this case, the source code is available, to download the dependencies the user must excecute the./gradlew expandModules
Gradle task and then compilation is required.JAR
: In this case, a standard format for java packages distribution, these include the compiled Java classes, and the dependencies resolution is dynamic.Local
: The local format implies that the module is installed but it is not declared as a repository dependency.
- Installation Status: It describes the dependency current status.
- Pending download: This is the status by default when a new dependency is added or updated. To be installed, it is necessary to compile the environment and, in such case, the dependency is in
source
format. - Installed: Used once the dependency is already installed.
- Pending download: This is the status by default when a new dependency is added or updated. To be installed, it is necessary to compile the environment and, in such case, the dependency is in
- Module: A reference that appears to the module when it is installed.
- Version Status: It describes the dependency version status.
- Untracked: Only for external and local dependencies.
- Update Available: In case there are new available versions.
- Updated: The latest available version is installed.
- External Dependency (Only available for
JAR
dependencies): Checkbox that identify an external library or module required by the project, managed by Gradle. These dependencies are retrieved from remote repositories during the build process.
Buttons
Change Version
This button is used to update or downgrade versions.
When the version of a module is modified, its related dependencies could be modified as well. In this case, it is possible to add new, update or delete versions.
Warning
A warning notification is shown to inform the user about versions compatibility before executing the process.
Change Format
This button is used to change the format of the module. This process needs to be executed when it is necessary to migrate from a local format to a gradle dependency, while keeping the modules updated. The options are source
, JAR
or local
.
-
In case the module is originally in
local
format, the options in the Change format popup window areJAR
orsource
. -
In case the module is originally in
source
format, the only option in the Change format popup window isJAR
. -
In case the module is originally in
JAR
format, the only option in the Change format popup window is source. In this case, the window shows a warning notification to remind the user that the original directory is deleted once the process is finished.
Delete Dependency
This button is used to delete dependencies.
-
JAR format dependency: In case you need to remove a dependency to actually complete the action, the environment must be compiled.
-
Local or Souce format dependency: In case you need to remove a dependency to actually complete the action, the environment must be compiled. Also, note that both
Source
andLocal
dependencies must be manually removed from the/modules
folder prior to compilation.Warning
A warning notification is displayed to inform the user of the steps to remove it.
Add Local Dependencies Process
Application
> Etendo Dependencies Management
> Add Local dependencies
This process, in Add Local dependencies
window, also part of the Dependencies Management, is in charge of identifying all the locally installed modules without related dependencies, add them to the Dependency Management window with the local
format.
Note
The main objective of this process is to add the dependencies in local
format, so that in case of being distributed as an Etendo module it can be easily migrated to Sources
or Jar
format.
Update Packages Information Process
Application
> Etendo Dependencies Management
> Update Packages Information
Since the information about packages is daily updated, the user can execute manually the process from Update Packages Information
window to update the list of packages with the latest information.
Info
The same process can be executed from the Module Management window, selecting one record and clicking the Update packages button.
Note
Each time the server is restarted, the update process is executed automatically.