How to create a Payment Terms Module
| Languages: |
English | Translate this article... |
Contents |
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 common payment terms used in 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 payment terms module is to provide a dataset with the list of the payment terms commonly used in 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 payment terms.
From the functional side it is mandatory to understand the way payment terms are configured in Openbravo. Please read the Payment Term article for more information.
Estimated effort
A payment terms module is one of the easiest and fastest module to develop. Probably the only difficult part is to properly configure and test the payment terms we want to include into the module. In general creating a payment terms module should take a few hours for any experienced developer.
Introduction
A payment term specifies the way and period allowed to pay off an amount due. For example, a business partner may demand a deferred payment period of 30 days or may even demand to partially pay their debts or collects in two or more deferred periods.
An unique payment term must be associated with an invoice, and defines the list of scheduled payment/s -including a due date and an expected amount to be paid or collected- that will be generated when completing the invoice.
Although the payment terms depend on the agreements between the organization and the business partners, there is usually a list of the common payment terms used in a country, making it a perfect candidate for a localization module.
Defining the Payment Terms
Setting up the environment
Each time we work with datasets it is highly recommended to do it inside a clean client. This simple trick considerably reduces the risk of including wrong data inside our dataset.
As System Administrator, we create a new client called PaymentTerms:
Now we should log out and log in inside our PaymentTerms client.
Entering the Payment Terms
On the Payment Term window of our recently created empty client, we must enter the Payment Terms to include into the module. Example of Payment Terms are: Immediate, 100% in 120 days, 50% in 30 days and 50% in 60 days, etc.
Payment Terms Translation
Notice that the payment term name and description must be written in the country language. In case you country has several official languages, you can also define the correspondent translation inside the Translation tab.
Once we have created the translations for all the payment terms we have two possibilities:
- To include the translations inside the payment terms module's dataset. This is the fastest solution, and it is only possible if we are the owners of the payment terms module.
- In case we want to create the translation for a third party payment terms module, we must create a new module with a dataset which just includes the translated records and that will depend on the original payment terms module.
In the Dataset definition chapter we will see how to export these translations (and the rest of the payment terms configuration).
Creating the Payment Terms Module
At this point our PaymentTerms client should have all the payment terms that we would want to include into our module. It is the time to create it.
Module definition
As you already know, a payment terms 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:
- You should try to follow the Naming guidelines for modules
- The flag Has reference data must be set. Remember to write any useful information inside the Reference Data Description field which will be read by the user when applying the dataset.
- Inside the Dependency tab, include the mandatory dependency to Core.
After the module's definition is ready, you should register the module in case you want to publish it in the Forge
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:
- The dataset must belong to your payment terms module
- Try to avoid strange characters in the dataset name. This string is used for generating the XML file name that stores the dataset.
- The Data Access Level must be set to Client/Organization, which means we allow users to apply the payment terms configuration either at Client level (Organization *) or at Organization level.
- The Export allowed flag must be set.
- Inside the Table tab we must register all the tables to be included into the dataset. The list of tables is:
- C_PaymentTerm, which stores the Payment Term headers
- C_PaymentTermline, which stores the Payment Term lines
- The HQL/SQL Where clause is a very important field, because it allows us to filter the records we want to include into the dataset. If you remember, at the beginning of this document we proposed to create a new empty client called PaymentTerms in which define our payment terms configuration. In the example bellow we have used the client.name='PaymentTerms' clause to get only the records that belong to this client, which are the only ones we want to distribute in our payment terms module.
- Finally, if you want to include the translations into the payment terms dataset, you should also create new records for the C_PaymentTerm_Trl table. Note how we can filter the records inside these tables by the language definition. Example: language in ('en_US').
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 verify 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.
Testing the Dataset
The real test to ensure the payment terms dataset is OK can be done inside our development instance. The test consists on creating a new client running the Initial Client Setup and selecting our payment terms module dataset at the Reference Data section.
If the data inside the dataset are consistent, the Initial Client Setup Process should be completed successfully, otherwise it will fail giving a description about the error.
After a successful Initial Client Setup, we just need to login in the new client, go to the Payment Term window and check all the payment terms have been inserted.
Packaging the module
To generate the obx file we should follow the standard steps from the command line:
- Export the database:
ant export.database
- Package the module:
ant package.module -Dmodule=<payment methods module java package>
- We can now publish the module in the Central Repository
Considerations when releasing new versions
If you plan to release new versions of the payment terms 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.