ADempiere 3.6 Cookbook: Over 100 recipes for extending and customizing ADempiere beyond its standard capabilities

In this chapter, we are going to look at the overall customization capability of ADempiere. Many of them can be achieved by configuring ADempiere. However, many of them require a combination of customization and configuration. Here we will deal with words like Table, Column, Window, Tab, Field, Process, Model, Validation Rules, and so on and see how to create a new entity of each kind.

To make the topics relevant and have a logical flow, II will be taking a case study and implementing a small module called Minutes Of Meeting (MOM). This module is intended to allow the user to capture the minutes of a meeting and carry out various tasks related to it. As we progress through the recipes, we will cover the concept, its application to the business, how it maps to this MOM case study, and then we would look at what it takes to implement in ADempiere. Going forward, I will be using the following MOM template, as shown in the following screenshot, to map ADempiere capability.

Before...

A window provides create, read, update, and delete (CRUD) access to the data to a user. These functionalities are provided by the standard tools and menus. A standard layout of a window has the following parts:

The following screenshot shows the different parts:

Given the ADempiere architecture, as an author of a new window, you do not have to worry about how and what gets displayed in the Title, Menu bar, Tool bar, and Status bar. All we need to focus on is the Tabs panel. And, in this recipe, we will go through the steps required to create a complete working new window in ADempiere, which will act as the foundation for building our MOM window.

Practically, there will be a situation when we will have to make changes to the existing screens. For example, label change, data type change, logically grouping the fields, and so on. In this recipe, we will take our newly created MOM window and we will customize it further to understand the process involved in customizing an existing window.

In the previous recipe, our window had a Start Date, Start Time, and End Time. All of them display both the date and time. Now, say, we want to achieve the following:

Given this customization need, let us see how we can achieve it.

It is pretty common to logically relate the information using tabs. This recipe describes the steps to add multiple tabs in a window. So far, we have our basic MOM window. Now, we will break it into multiple tabs:

On the MOM tab, we have the Chairperson field where we are entering the username. Similarly, we have the participant's name on the Participants tab and the Actioned By person name on the Discussion Detail tab. ADempiere maintains User/Contact detail. To provide a better finishing of our MOM window, it would be good if we can connect these fields with ADempiere's User/Contact so that a user can find the right User/Contact and assign them to a MOM. This way, all these fields need to be made like a search widget where a Search button appears next to these fields. When a user clicks on the Search button, he/she will be able to find the User/Contact, and upon selection, the selected User/Contact will appear in the field. As part of this recipe, we will follow through the steps required to convert each of these fields into a search widget.

DROP TABLE adempiere.c_mom_participantsline...

There is a Status field on the Discussion Detail tab. Currently, this field accepts free text. For various practical reasons, such as, to maintain the consistency in communication, to support project guidelines, to have clean data for further analysis and reporting, and so on, it makes sense to convert the Status field into a combo-box and the possible values are listed for the user selection. In this recipe, we will follow the steps to convert the Status field into a combo-box and configure it in such a way that it is populated with values.

ALTER TABLE c_mom_discussionline DROP COLUMN status;

In the previous recipe, we created a c_momstatus table and created a column, c_momstatus_id, in the c_mom_discussionline, which has a foreign key relationship with the c_momstatus table. This is a useful detail in the context of the Zoom window, as ADempiere automatically generates a link (called hyperlink in the web version) and when we click on the link, the system takes us to the linked window, which is called zooming in ADempiere. This is useful when you are on a window and quickly jump on to another window, which is linked through one of the fields to look at more details. However, there are some other details that need to be configured before it starts working and this recipe will cover these details.

In contrast, there will be situations where a user is required to only look at the details and not required to create the record. For example, a customer service representative only requires view permission on most of the data so that they can answer customer enquiries effectively. This recipe describes how we can create a read-only window.

How to do it...

To demonstrate, I have taken the MOM Status window. However, you may apply the same steps to your Minutes Of Meeting window.

1. 1. Log in as System/System with the System Administrator role.

2. 2. Go to the Window, Tab, and Field window and look for the MOM Status window.

3. 3. Change the Window Type to Query Only and save it, as shown in the following screenshot:

1. 4. Log out and log in as GardenAdmin/ GardenAdmin with the GardenWorld Admin role.

2. 5. Go to the MOM Status window. System will show you the list and the New Record button will be disabled, as shown in the following screenshot:

Sometimes there may be a need where not the complete window should be made read-only. Rather, a particular tab needs to be made read-only. For example, there is a user who, as per their role, shall capture the payments against an invoice. He/she should not be allowed to create an invoice in the system. To address this need, we can have a window where one tab is to capture the payment detail and another one showing the outstanding invoices, which we will make read-only. This way, on the single window, the user will be able to refer to the outstanding invoices and at the same time receive payments towards them.

In our MOM case study, Let us say we want to add a rule that states only an admin user shall be allowed to edit the discussion items of an MOM. Let us see how we can do this.

Another situation is where neither a window is read-only nor is the tab. It is there that we want to make a few fields read-only on a tab. For example, on our MOM window, the Client and Organisation fields need to be read-only as they are populated, by default, based on the logged in user's details and does not require any modification. This recipe describes the steps to achieve this.

How to do it...

1. 1. Log in as System/System with the System Administrator role.

2. 2. Go to the Window, Tab, and Field window and look for the Minutes Of Meeting window.

3. 3. Select the target tab on Tab and go to the Field tab.

4. 4. Check the Read Only checkbox for the Client field, as shown in the following screenshot:

1. 5. Repeat the same for Organisation and any other field that you want to be read-only.

2. 6. Log out and log in as GardenAdmin/ GardenAdmin with the GardenWorld Admin role.

3. 7. Go to the Minutes Of Meeting window. Editing will not be allowed for all the fields we marked as read-only...

As part of the customization, we may build windows and may want to keep them logically grouped. For example, in ADempiere, we have Quote-to-Invoice where everything related to the sales is grouped. Let us say we want to group all our MOM-related windows under a node MOM in the Menu tree so that they are all in one place. Here we will look into the procedure to create such a menu structure.

How to do it...

1. 1. Log in as System/System with the System Administrator role.

2. 2. Go to Menu | System Admin | General Rules | System Rules | Menu.

3. 3. Click on the New Record button to create a new menu and fill in the details, as shown in the following screenshot:

• Check the Summary Level to create a folder entry in the Menu tree to which further menus can be added. If the Summary Level is not checked, the newly created menu will be added a leaf node to the Menu tree.

1. 4. Go to Menu | System Admin | General Rules | System Rules | Tree Maintenance and select Menu from the Tree drop-down...

By default, to every role in ADempiere, we see a Menu tree, which shows the items that the role has access to. It is imperative that, for a role, we may have to build an altogether different menu tree. For example, a sales representative in an organization requires access to Quote-to-Invoice. In that case, that role shall see only the Quote-to-Invoice node in its Menu tree.

Let us say, in our MOM example, there is a user role, which only needs to work with the MOM-related windows. To such a role, we would like to ensure that only the MOM node appears in their Menu tree. This recipe provides us with the required details to implement our requirement.

How to do it...

1. 1. Log in as System/System with the System Administrator role.

2. 2. Go to the Menu | System Admin | General Rules | System Rules | Tree window.

3. 3. Click on New Record and fill in the required details. For Type | Area, select Menu, as shown in the following screenshot:

1. 4. Click on the Verify...

By default, ADempiere shows data in a window in multi-row mode, where it shows multiple records in a tabular format. It allows complete data entry in the tabular form, as well. However, in many instances, it is more logical and convenient to show the window as a form to allow easy understanding and filling of the data. Irrespective of the default mode, using the Grid Toggle toolbar button, a user can switch between these two modes. However, from a usability perspective, many a times, it makes sense to show the window as a form or as a table. For example, if the workflow says that a user has to always create the data in the system, it is more appropriate to provide the single-row mode (window is shown as a form) of the window to that user. Whereas, if the workflow requires the user to create the data (only if it does not exist in the system), it is more appropriate to show the window in the multi-row mode (tabular representation). This...

On our MOM window, we have MOM, Participants, and Discussion Detail tabs. Let us say we think it would be better if Participants information is displayed on the first tab, MOM. This way, one can quickly find out who all attended the meeting, if that is the only interest they have in this window. Here we will go through the steps required to have a tab included inside another tab.

How to do it...

1. 1. Add a new column to the adempiere.c_mom table by executing the following SQL:

   ALTER TABLE adempiere.c_mom ADD COLUMN tab_participants numeric(10);
   

2. 2. Go to the Table and Column window and generate the new column from the database table, as shown in the following screenshot:

1. 3. Go to the Window, Tab, and Field window and generate the new field.

2. 4. Verify the field sequence. Usually, we would like to keep these kinds of things at the end, as shown in the following screenshot:

1. 5. Go to the Field tab and select Participants from the Included Tab drop-down...