How to create a Payment Methods 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 methods for 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 methods module is to provide a dataset with the list of the payment methods 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 methods.
From the functional side it is important to understand the financial flows based on the new Advanced Payables and Receivables module. Specially important is the article that explains the Payment Methods.
Estimated effort
A payment methods module is one of the easiest modules in a localization project and its development time is probably the fastest one. Any developer with some experience in Modularity can create a Payment Method module in less than two hours.
Introduction
Payment Methods represents means of payment used by enterprises or business partners, like cash or credit card. Based on the Payment Method configuration, Openbravo automatically defines a particular payment flow. Any Payment Method can be associated with a business partner or a financial account.
By default there is no an existing list of “Payment Methods” in the Advance Payables and Receivables Management module and it is up to the user to create his own payment methods. So the objective of a Payment Methods module is to provide a dataset that includes the base list of common payment methods used in a country.
Defining the Payment Methods
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 PaymentMethods:
Now we should log out and log in inside our PaymentMethods client.
Entering the Payment Methods
Inside our recently created empty client, we must enter the Payment Methods we want to include into the module. This can be done at the Payment Method window. Example of Payment Methods are: Cash, Credit Card, Wire Transfer, Certified check, Check, Cash on delivery, Receipt, etc.
Take into account that only the name and description fields will be included into the module's dataset. Please notice that these fields will be read by our users, so they must be written using the country language.
When installing the module all these payment methods will share the same default configuration. The end-user should then decide which of the provided payment methods to use and the right way to configure them depending on his personal preferences.
Creating the Payment Methods module
At this point our PaymentMethods client should have the list of payment methods that we would want to include into our module. It is the time to create it.
Module definition
As you already know, a payment methods 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.
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 methods 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 methods configuration either at Client level (Organization *) or at Organization level.
- The Export allowed flag must be set.
- Inside the Table tab we must include the FIN_PaymentMethod table, which stores the payment methods we have previously defined.
- 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 PaymentMethods in which define the list of payment methods. In the example bellow we have used the client.name='PaymentMethods' clause to get only the records that belong to this client, which are the only ones we want to distribute into our module.
- The Include All Columns flag must be set to No. The reason is that we only want to include the name and description columns into the dataset, otherwise the end-user configuration could be override in each module's update.
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 the table.
Testing the dataset
The real test to ensure the payment methods 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 methods 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 showing a description about the error.
After a successful Initial Client Setup, we just need to login into the new client, go to the Payment Method window and check all the payment methods 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 methods 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.