INTRODUCTION TO EXTENSIONS
This Chapter describes the Extensions functionality in Compiere.
In addition to the internal application dictionary based customization capability; Compiere also provides the ability to extend the application. In contrast to other applications, client extensions are possible in a hosted environment and are maintained during upgrades.
If the information structure is not sufficient, users can add fields to any record with its presentation and validation rules. Data entry can be made mandatory, if certain conditions apply. The entry validation can be based on lists, tables, or functions like call outs.
Compiere Scripting allows the user to extend the functionality using Java syntax. It is also used for conversion.
Functional extensions are implemented via 'call out' technology. Clients can provide additional functionality in Java or even native C functionality, e.g. for additional validation or data feeds. Call outs can be invoked before or after data entry in any field. Compiere ensures that call outs cannot crash or corrupt the system.
The advanced user can extend and in certain areas modify the rule base. Rules are organized in packets making sure that transaction integrity is maintained. Rule extensions could be used for generating statistical entries or special reporting needs.
Currently, rules are used for creating accounting transactions and for pricing.
Application Extensions Framework
The current framework will allow Partners to create application extensions that include both reference data and code, and can be distributed to their customers through Compiere.
Procedure for Implementation of Application Extensions
Elements that could be packaged as part of application extensions include: localizations, translations, industry solutions, customer solutions, etc. These elements can be developed and packaged independently, while Compiere will continue to be the provider of the distribution and installation mechanisms.
Important: Those who intend to use this feature must contact Compiere before attempting to register application extensions.
The steps for partners to generate application extensions:
- Register application (using Compiere window Entity Type)
- Develop application
- Create application .car file (using Compiere window Entity Type)
- Upload application file to Compiere
For customers to install the application extension:
- Buy application from Compiere marketplace
- Download application .car file
- Install application
Register an Application Extension
Use the following steps to register for Application Extensions:
Contact Compiere using the Contact Us page from our website or by sending an e-mail to email@example.com before trying to register your new application extension.
Afterwards, log into Compiere as the System Administrator role.
Open the Entity Type window (Application Dictionary => Entity Type) and create a new record.
Important: Be careful not to modify the entities C, D, CPRO or XUOM.
Complete all the mandatory fields. For entity type, notice that names beginning with "C" are reserved for Compiere and you must use four characters.
Comments about optional fields:
- Version: The version of your extension. Usually 1.0 for the first version.
- Prerequisite version: The Compiere Core version that is required for this extension, e.g. 3.0.3. You need to use the exact text as defined for the entity type D
- Prerequisite applications: The entity type of the applications that need to be installed in order to install this extension. For example, set it to CPRO if the extension must be applied on top of the professional edition.
- Classpath: List of additional jar files required for this extension.
- Model package: Specific model package from the jar files listed in the classpath field.
You do not need to enter any information on the Version, Modification, or Migration Step tabs.
Ensure that your System window contains your up to date information for your system and web store email/password information
Click "Register Application" to send your request to Compiere.
Important: If an entity type with the same name has already been registered you'll get an error "Error: Already registered: XXXX". You will have to create a new record with the new entity type. Verify with Compiere that the new entity type that you plan to use is available.
At the prompt, click 'Ok' to start process.
Leave the defaults in place and click 'Ok' to continue.
At this point the status will be pending approval from Compiere. A Compiere representative should contact you soon to confirm the registration or to ask any additional questions.
Creating Data Dictionary changes
Once your registration is approved, you can start creating data dictionary entries and mark them with your entity type. Please refer to the Data Dictionary section for details about how you can create data dictionary entries.
View Data Dictionary changes
After you have finished making your changes, you can view a summary of all the changes that have been done for a particular entity type by using the Data Migration Preview feature.
In order to access this feature, first enable beta functionality for the System tenant. This can be done in the Tenant window.
Once you have enabled beta functionality for the System tenant, you should be able to access the Data Migration window. Create a new Data Migration record, select your entity type, and click on the Create Preview button. Be sure to check the include Entity Type Data check box. As the name suggests, this option will tell Compiere to automatically include all changes marked with the entity type of the Data Migration. Click okay to create the preview.
Upon a successful completion of preview, you will see something similar to this in the Preview tab:
The screen shot above shows the result of what happens when we specify Compiere Warehouse Management System as the entity type. The Preview shows what data dictionary entities are marked with such entity type and the other data dictionary entries that they are dependent on or are dependent on them. For example, in the screen shot above, you can see that the Preview includes the Zone window (level 0). It also includes the Replenishment tab (level 1) as the tab is a dependent of the Zone window.
Note that Compiere uses the same logic as the Data Migration Preview creation logic when it creates an Application .car file. So you can use the Data Migration Preview to verify that all of your data dictionary changes are included. You can also use this feature to investigate why other data that are not marked with your entity type are included.
Creation of Application .car file
After verifying that all of the data dictionary changes are taken into account, you are ready to create an Application .car file.
Use the following steps to create the Application .car file:
Generate jar files for the custom code required by your extension.
Login to Compiere with the System Administrator role and query the entity type that you registered in the previous step and click "Create Application File."
At the prompt, click 'Ok' to start process.
Next, Provide the directory for the jar file directory.
The car file will be generated in the COMPIERE_HOME/data directory with the name compiere_'<entityType>'.car
Installation - Application
Use the following steps to install the Application:
After obtaining the car file for the application extension, copy it to the directory COMPIERE_HOME/data.
Execute RUN_Setup (see Appendix A for details on the setup information.)
Important: Be sure to have internet connection available to be able to get the license terms for the application extensions that you plan to install.
When you get to the window to select the applications, besides the application extension that you need to install, also select the option Reinstall/Migrate for Compiere Core 3.0.3 or later.
Then continue with the Migration steps as usual.
Creating Migration Steps
There are times when you need Compiere to perform very specific tasks when installing your application extension. If Compiere does not already handle such tasks by default, you can create a migration step and define in it either a SQL logic or a Java class that perform such tasks.
First, define the version that the Migration Steps will apply to.
Migration steps defined under version X will be executed when Compiere migrate from version A to B if A < X <= B. The exception to this is the 'Final' version. Migrations steps defined under the 'Final' version will always be executed. In the example above, we have defined two versions: '310' and 'Final'. So when you install 'WCOM' on a Compiere instance that has a version of 310 or lower, Compiere will execute the migration steps defined under version '310' and 'Final'. If instead you install 'WCOM' on a Compiere instance that has a version higher than 310, then only those steps defined under the 'Final' version will be executed.
After you have defined the version, you can define the migration step.
Specify a timing type to tell Compiere when to execute this migration step:
- Before Structure Executed before Compiere performs any database changes
- Before Data Executed after Compiere has updated the table and column definition in the database but before synchronizing the data in those tables.
- After Data Executed after Compiere has finished synchronizing the data in all database tables.
Specify the type of the code that you want to associate with this migration step.
For SQL, specify a valid SQL statement in the Code field. You can optionally specify a Database Type if this migration step should only be applied for a specific database type. If none is specified, the migration step will be applied to all databases.
For Java, specify a Java class that implements the MigrationStepInterface interface. The interface consists of one method executeStep() that returns null if the execution is successful or an error message if not.
Note that it is imperative that the code that you have defined is safe to be run multple times. The reason is because a user may install your application multiple times (e.g. if installation or migration did not complete successfully earlier).
Finally, specify if it is okay for migration step to fail. By default, Compiere will print treat failures in executing a migration step as an error. If you mark a migration step as okay to fail, Compiere will not treat them as an error and will only print a warning message in the migration log file.