ERP 2.50:Developers Guide/How to develop a new window
Languages: |
Contents |
Objective
The objective of this how-to is to show how you can create a new window from scratch. The how-to starts with creating a new table and then takes you on to creating the window itself and adding it to a module.
The how-to is based on the following scenario: imagine we are developing an HR module and we need a window that will enable the user to input salaries of employees. We also need to track the employee's salary so history records need to be preserved. Each salary record needs to have a Valid From Date field that indicates when a particular salary came into being. The record belonging to a particular employee with the latest Valid From Date is the salary that is valid today. Note that employees are already inside the system contained in the C_BPARTNER database table and indicated by the C_BPARTNER.ISMEPLOYEE column. Therefore, we only need to create a database table that will hold the actual salaries.
Module
All new developments must belong to a module that is not the core module. Please follow the How to create and package a module section to create a new module.
![]() | Note the DB Prefix defined there is HT which will explicitely indicate the prefix of our new database table! |
Creating new tables in the database
Let's introduce a new database table called HT_SALARY that will hold the required data. Notice the HT prefix of the table name indicating the module this table belongs to.
The new HT_SALARY table must include the AD_Client_ID, AD_Org_ID, IsActive, Created, CreatedBy, Updated and UpdatedBy fields that are mandatory and required for security and auditory purposes of the application.
Column name | Type | Length | Note |
---|---|---|---|
HT_SALARY_ID | CHAR | 32 | The primary key of the table that must follow the table name followed by the _ID. |
AD_CLIENT_ID | CHAR | 32 | Indicates which client (company) the record belongs to (multitenancy). |
AD_ORG_ID | CHAR | 32 | Indicates which organization (city/department/location) within a client a record belongs to. |
ISACTIVE | CHAR | 1 | This is intended for deactivating records that are not valid anymore but are referenced within the system and hence cannot be deleted. |
CREATED | DATE | Date/time of creation of a record. | |
CREATEDBY | CHAR | 32 | Foreign key to AD_USER indicating the user that created this record. |
UPDATED | DATE | Date/time of last update of a record. | |
UPDATEDBY | CHAR | 32 | Foreign key to AD_USER indicating the user that last updated this record. |
C_BPARTNER_ID | CHAR | 32 | Employee this salary belongs to. |
AMOUNT | NUMBER | 10 | The actual amount of the salary. |
C_CURRENCY_ID | CHAR | 32 | Foreign key to C_CURRENCY indicating the currency the amount is in. |
VALIDFROM | DATE | Date that this salary is valid from. |
To create the above table within the database, use one of the following CREATE TABLE statements depending on the DB you are using:
PostgreSQL
CREATE TABLE HT_SALARY ( HT_SALARY_ID CHARACTER VARYING(32) NOT NULL, AD_CLIENT_ID CHARACTER VARYING(32) NOT NULL, AD_ORG_ID CHARACTER VARYING(32) NOT NULL, ISACTIVE CHARACTER(1) NOT NULL DEFAULT 'Y', CREATED TIMESTAMP WITHOUT TIME ZONE NOT NULL DEFAULT now(), CREATEDBY CHARACTER VARYING(32) NOT NULL, UPDATED TIMESTAMP WITHOUT TIME ZONE NOT NULL DEFAULT now(), UPDATEDBY CHARACTER VARYING(32) NOT NULL, C_BPARTNER_ID CHARACTER VARYING(32) NOT NULL, AMOUNT NUMERIC NOT NULL, C_CURRENCY_ID VARCHAR(32) NOT NULL, VALIDFROM TIMESTAMP WITHOUT TIME ZONE NOT NULL, CONSTRAINT HT_SALARY_ISACTIVE_CHECK CHECK (isactive = ANY (ARRAY['Y'::bpchar, 'N'::bpchar])), CONSTRAINT HT_SALARY_KEY PRIMARY KEY (HT_SALARY_ID), CONSTRAINT HT_SALARY_AD_ORG FOREIGN KEY (AD_ORG_ID) REFERENCES AD_ORG (AD_ORG_ID), CONSTRAINT HT_SALARY_AD_CLIENT FOREIGN KEY (AD_CLIENT_ID) REFERENCES AD_CLIENT (AD_CLIENT_ID), CONSTRAINT HT_SALARY_C_BPARTNER FOREIGN KEY (C_BPARTNER_ID) REFERENCES C_BPARTNER (C_BPARTNER_ID), CONSTRAINT HT_SALARY_C_CURRENCY FOREIGN KEY (C_CURRENCY_ID) REFERENCES C_CURRENCY (C_CURRENCY_ID) );
Registering the table within the Application Dictionary
The following steps register the newly created table within the Openbravo ERP Application Dictionary.
For this purpose, first log into Openbravo ERP using a username with access to System Administrator role. Navigate to Application Dictionary || Tables and Columns and create a new record as shown in the screenshot below:
Main fields of this window are (for more information see the AD_Table table description):
- Data Package specifies to which java data package within the module the table will belong when used within DAL (Data Access Layer).
- Name Defines the name that Openbravo ERP uses to recognize the defined database table.
- Description Gives a small description of the table.
- Help/Comments Defines the text that is displayed in Help window.
- DB Table name Defines database table name as it was defined by the CREATE TABLE during its creation.
- Java Class Name This will be the actual Java class within the Data Package of the module through which you will be able to access this table when using DAL.
- Data Access Level determines what kind of data will the table contain due to the multitenancy functionality
- System only: Only system records can be inserted into this table (AD_CLIENT_ID=0, AD_ORG_ID=0), for example AD_TABLE.
- System/Client: System or client specific records can be inserted here (AD_CLIENT_ID=anything, AD_ORG_ID=0), for example AD_ROLE
- Organization: Only client and organization specific data can be inserted into this table (AD_CLIENT_ID<>0, AD_ORG_ID<>0), for example C_INVOICE
- Client/Organization: Only client specific data can be inserted here, however, it can belong to a specific organizations within that client or be shared among all (AD_CLIENT_ID<>0, AD_ORG_ID=anything), for example C_BPARTNER
- All: Any combination of AD_CLIENT_ID and AD_ORG_ID can be inserted into this table.
Save this record then press Create columns from DB button to create columns within the Column tab automatically.
Once the creation process has finished, you will be informed of the number of columns that have been added to this table.
Switch to Column tab to see all the columns that were created according to their definition within the database. You can now additionally alter the properties of each column. Each column is assigned a reference (which defines the data type) depending on its name and its data type. Run Synchronize Terminology process (Application Dictionary || Synchronize Terminology). For more information see the AD_Column table description.
This process tries to find an existing application element (within the currently developed module) and thus its label, help and description and if one is not found, a new one is created. This enables a centralized translation of the application/module.
Each table must have at least one column marked as an identifier. The actual values of identifier columns later get concatenated to be shown to the user as a representation of a particular record (see the link to the Sales Order within the Sales Invoice window). These identifiers will also be used to construct dropdown lists of records of that particular table. By default all columns with column name Name are set as an identifier. In case there is no column with this Name, no identifier is set and needs to be done so manually or compilation will fail.
Most of the columns in our specific HT_SALARY case will be automatically detected correctly, however, some need revising:
- Amount: Reference = Amount, Length = 10
- C_BPartner_ID: Reference = Search, Reference Search Key = Business Partner, Link To Parent Column = Y
- Valid From: Identifier = Y
- Amount: Identifier = Y,
- Date Fields (Updated,UpdatedBy...) = Date
Openbravo ERP now knows about the new HT_SALARY database table and how to treat it in terms of its definition and the representation to the user.
Creating a New Window
Using the System Administrator role navigate to Application Dictionary || Windows, Tabs and Fields. Create a new record as indicated by the screenshot below:
Although in the image the name used is Employee Salaries, it is an error and should be Employee Salary
Main fields of this window are (for more information see the AD_Window table description):
- Name Defines the name that Openbravo ERP uses to recognize this window.
- Description Gives a small description of the table.
- Help/Comments Defines the text that is displayed in Help window.
- Window Type Defines some user interface specifics for a window:
- Maintain: is used for windows with few entries.
- Transaction: for transactional windows.
- The header tab's underlying table must contain the PROCESSED and UPDATED columns
- by default this window filters out old (n days – General Setup > Application > Session Preferences window setting) and processed documents.
- Query Only: for read-only windows that only enable viewing of data.
Save this record and move to Tab tab. Create a new record as shown below, creating the first tab to show the employee information:
Main fields of this window are (for more information see the AD_Tab table description):
- Name Defines the name that Openbravo ERP uses to recognize this tab.
- Description Gives a small description of the table.
- Help/Comments Defines the text that is displayed in Help window.
- Table Specifies the table that the tab will show the data from.
- Table Level Defines the hierarchy of tabs, 0 being the highest level.
- UI Pattern This dropdown offers the following options:
- Standard - standard interface where multiple records can be added, viewed and edited
- Read Only - this option disables any editing/creating capabilities for any user within this tab
- Single Record - this option enforces a one-to-one relationship between a parent and a child tab, allowing the user to enter maximum one record in the tab
- SQL Where Clause By using this SQL filter, the user will never be able to see data that does not fit the criteria. In our case, we use it to display only business partners that are our employees.
Save this record and then click the Copy Tab Fields button to copy fields from the existing main tab of the Business Partner window into our new one. Select the Business Partner-Business Partner Tab - Window combination and confirm the dialog with OK.
Move to Field tab to see all the created fields.
If required, changes to these fields could be made or new ones could be added manually. For more information see the AD_Field table description. However, in our case we are happy with the way they are.
Now, go back to Tab tab and create a new record that will represent the child tab of the Employee tab where salaries will be managed:
Most importantly, make sure you select:
- Table = HT_Salary
- Tab Level = 1
For more information see the AD_Tab table description.
By clicking and confirming the Create Fields dialog, the application will automatically insert the columns of the selected table into the fields tab of the Salary one.
Then, move to Field Sequence tab to define which fields will be displayed (right side) and which not (left side) and the order of displayed ones (up and down arrows). See the snapshot below to order them according to common look and feel of other windows and Save.
For Openbravo to create links (labels that appear blue) to table elements, the system needs to know which window represents the table where a certain element resides. In our case, the Employee Salary window is used to manage the content of the HT_Salary database table. Hence, all salary records need to be shown within that window. To indicate that go to the Application Dictionary || Tables and Columns window, find our HT_Salary table and set the Window as indicated below:
Creating the Menu Item
A menu item is required for the user to be able to call up the new window we developed. Using the System Administrator role navigate to General Setup || Application || Menu and create a new record:
Main fields of this window are (for more information see the AD_Menu table description):
- Name Defines the name that Openbravo ERP uses to recognize this menu item.
- Description Gives a small description of the table.
- Summary level Defines a folder containing menu items (windows, processes, reports and so on).
- Action Defines the type of menu item.
- URL If Action is External link or Internal link, defines the URL to be linked.
- Special Form If Action is Form, defines the form to be linked.
- Process If Action is Process, defines the process to be launched.
- Report If Action is Report, defines the report to be linked.
- OS Task If Action is Task, defines the operating task to be launched.
- Window If Action is Window, defines the window to be linked.
- Workflow If Action is Workflow, defines the workflow to be linked.
Save this record then click on Tree icon .
Her you can drag and drop the new Employee Salary menu item to any of the other menu groups.
Compiling the Application with the New Window
Finally, the application needs to be recompiled in order to generate the new window's code and deploy it to Tomcat. If using Eclipse, use the eclipse.compile ant task and enter Employee Salary into the dialog that pops up. If manually compiling Openbravo, use the ant compile.development -Dtab='Employee Salary'
Important note: once the compilation has finished, restart Apache Tomcat server. In Windows, it is best to stop the Tomcat before running the build task and the start it again afterwards since Windows locks certain files the the compile.development build task might not be able to copy over. |
See more on Build Tasks.
The Result
Using the Openbravo Admin role, select the link to the new window from the menu. Notice the new window and the two tabs hierarchically positioned one above another (one Employe can have one or more salary records):
By double clicking John Moneymaker, details of this employee appear, however in a read-only mode (notice all fields are gray).
Then by moving on to the Salary tab, you will see an empty grid since we have not entered any salaries yet. Use the create new icon to create a new salary record as indicated below.
Save.
You have now successfully created your own new window and seen how it came to life within Openbravo ERP. Congratulations!
Languages: |
ERP 2.50:Developers Guide/How to change an existing window | ERP 2.50:Developers Guide/How to develop a callout