The original article was created by Andries L Pretorius on June 2010 at Open Source.
In this article on advanced aspects of Compiere by Andries L Pretorius, author of Compiere 3 Implementation Guide, we will cover:
- Overview of the Compiere Application Dictionary and its components
- Adding a custom field in Compiere
- Setting up a basic document process approval workflow in Compiere
The Compiere Application Dictionary (AD)
The Application Dictionary makes Compiere a truly unique and flexible business framework. Compiere was originally designed from the ground up on a model driven architecture (MDA), as defined by the Object Management Group (OMG). The system design conforms to an open standard in its layered architecture between business, application, and platform logic. MDA separates the business logic modeling, from technology modeling so as to ensure that both can evolve within their own domains, but still keeping within a framework of an open standard (and platform independent) that interconnects the two.
The benefit in the Compiere environment is that through modeling, design, and build the actual deployment time is greatly reduced. The AD also ensures a seamless upgrade of the platform while having little impact on the environment-specific business objects and processes.
The Application Dictionary of Compiere is meta data driven, meaning that contextual data defines the experience. This also means that the end user presentation layer and thus, the Graphical User Interface (GUI) platform have been defined in different technologies (i.e. Java Swing, HTML, and Ajax) and offers endless possibilities.
The Application Dictionaries can be illustrated as shown in:
[singlepic id=267 w=320 h=240 float=center]
To access the Application Dictionary you need to log in as a System Administrator and refer to the sub menu shown in:
We will use the Java Swing (Compiere Standard Edition) user interface for illustration purposes in this section.
[singlepic id=268 w=320 h=240 float=center]
Table and columns
This refers to the fundamental building blocks of the system, and links Compiere data to the underlying Table and Column structures in the database. Illustrated below is the Period table in the AD that links to the underlying table name of C_Period, which you will find in the database:
[singlepic id=269 w=320 h=240 float=center]
If the underlying database already contains the required fields, then by pressing the Create Columns from DB button and having the correct DB Table Name, Compiere will create the columns from the database in the AD.
Within a table, a key column must be created for use as the table identifier:
[singlepic id=270 w=320 h=240 float=center]
Illustrated the key column C_Period_ID. A column links to a System Element, as explained below, and is linked to the underlying table through the Synchronize Column button. In effect, synchronization creates or updates a column to the underlying database.
[singlepic id=271 w=320 h=240 float=center]
System elements
System elements are the common data elements and are used for central terminology references. These system elements link the underlying database columns to business-speak, for instance, in the screenshot in Image 5, C_Period_ID would be translated into the actual period.
[singlepic id=272 w=320 h=240 float=center]
System elements are also used for setting up translations, as well as help comments on column fields.
Validation rules
Field validation rules that are defined in the context of a column field are dynamically verified based on the predefined rules or user context, at time of rendering the data. For instance, when a Business Partner field is displayed for selecting, the Business Partner account must be active and not be a Summary Account as shown in Image 6.
[singlepic id=273 w=320 h=240 float=center]
Based on the example shown in Image 6, a dynamic validation will be set up for the C_BPartner_ID column field (the Business Partner table key identifier) on the Order table, shown in Image 7.
[singlepic id=274 w=320 h=240 float=center]
Reference
A Reference refers to database column field types that are either Data Types (i.e. an Amount, Integer, Date, Time, image, hyperlink, etc.) or a List validation (i.e. user pre-defined dropdowns) or Table validation (i.e. drop-downs for table key columns). An example of a Data Type column would be a period start date. The Column field StartDate in the Period table in the database is defined as reference Date
[singlepic id=275 w=320 h=240 float=center]
An example of a list validation on a Period Control Action (the actions that you can perform on a period) set-up is as shown in Image 9.
The list defined through a Search Key and a Name.
[singlepic id=276 w=320 h=240 float=center]
Search keys are saved in the database.
Table Validations are data-defined based on existing referenced key columns and SQL selection. An example of a table reference would be a Document type based on a table validation SQL query. Herewith, a Document type (C_DocType) is defined, but it refers to the appropriate Tenant/client so as to ensure that only the document types for a Tenant are displayed, shown in Image 11.
[singlepic id=277 w=320 h=240 float=center]
Windows, Tabs, and Fields
Compiere generates all of its windows in a standard dynamic way by reference to the defined AD. This AD window thus relates to setting up the Windows, and the Tabs(sub-linked windows) and Fields that are displayed on those Windows. Illustrated here is an example of the Calendar and Period window that defines the structure of the periods within Compiere.
[singlepic id=278 w=320 h=240 float=center]
Windows may be of the following Window Types:
- Maintain: Usually used in the context of master data, such as Business Partner or Products.
- Query Only: A window type that is used for displaying results in a grid, and is not editable.
- Transaction: A window type used for transaction processing , such as an order or an invoice.
The Window Tabs refer to the sub-linked windows of the main window header, or the preceding tab. In the example below, the Calendar window is built by defining the Calendar, applicable Year, Period and Period control, and Non Business Day.
[singlepic id=279 w=320 h=240 float=center]
The window's Fields are populated from the Table and Columns associated with the window.
[singlepic id=280 w=320 h=240 float=center]
Forms
Forms are windows that are not automatically generated through the AD but are static and are usually for custom purposes, based on specific Java code classes.Below is a Form that defines the File Import Loader process.
[singlepic id=281 w=320 h=240 float=center]
Once a Form has been defined, it is linked to the Java classes through the Classname(Swing) and Java Classname for Web UI fields. These classes will contain the source code to build these custom Forms.
Info windows
These are windows that are used for quick searches and information views. Here, is the Info window for viewing invoices. It is defined through an SQL query on a table and then defining the columns within the Info Window.
[singlepic id=282 w=320 h=240 float=center]
Report Views
Where database views may exist within the underlying database, the AD requires the Database views to be defined in the system in order to be accessible. Here, is an example of the Invoice database view for a week:
[singlepic id=283 w=320 h=240 float=center]
To distinguish them from normal tables, Compiere uses the RV_ prefix convention to name a Report View within the underlying database.
Reports and processes
These are used to set up reports (link to a Report view) or a process that can link to a Java code class. Reports and processes may have parameters that define a selection process. Examples of a report would be an invoice enquiry, and an example of a process would be to generate invoices from orders.Here is the actual Report that defines the Invoices per week report.
[singlepic id=284 w=320 h=240 float=center]
Reports may have access restrictions and selection parameters.
If a report is also displayed as a Dashboard (Compiere Enterprise version 3.5 onwards) then an underlying dashboard widget needs to be defined. An example of the Invoice Generate Process, that links to the underlying Java class:
[singlepic id=285 w=320 h=240 float=center]
In windows, Buttons may be linked to processes (i.e. C_Invoice Copy From which copies lines from other invoices on the Invoice windows) and Processes need not all be manually run as such. Processes can be defined as server processes, and can also be scheduled through the Compiere scheduler.
Adding a Custom Field in Compiere 3
The user menu is your default tree, and is accessed through the System Administrator role. You can find the Menu item in the screen tree:
[singlepic id=286 w=320 h=240 float=center]
The above screenshot illustrates a typical window set-up, which is done as follows:
- Create a new menu item by clicking on the New button. Enter a name and a description.
- Define its action type: A menu item's action type can be a Window, Form,Process, Report, Task, or Workflow. Link an AD item to the menu, which is illustrated above, where window Sales Order is linked to the Sales Order menu item.
- Move the menu item in context of the main menu tree for users understanding and access.
It is recommended that you define your own windows, or copy from the existing dictionary, for customizations. Because dictionary (system) defined items may be overwritten during the process of migrating to a new version, it is better to copy a window and customize it in the copied window (or create new). This applies to Java code as well: never change the original source as it may be overwritten during migration.
Adding a new field to a window and database
In this section we are going to illustrate how the System Administrator would go about adding a new field to the database. As an illustration, we are going to add a probability reference field that can be used to measure a predefined set of outcomes on an order to the Sales Order window.
- Find the context by Zooming to the Table from the Window. Open and find the Sales Order window in the Window, Tab, and Field menu item when logged in as System Administrator:
- Zoom from the window into the underlying Table and Column window.Order records are maintained in the database in the C_Order table:
- Next we refer the Column tab, and create a new column in the table(see the field naming conventions below). The new column must be as a System Element defined and hence we need to create a System Element prior to using it as a Column in the Table:
- Once the System Element has been defined, we set up the Column as follows:
- Create a new Reference key as follows:
- We then define the Reference key's list validation options as follows:
- The finalized column (and thus the ultimate window field) set-up is thus shown as follows:
[singlepic id=287 w=320 h=240 float=center]
[singlepic id=288 w=320 h=240 float=center]
[singlepic id=289 w=320 h=240 float=center]
[singlepic id=290 w=320 h=240 float=center]
[singlepic id=290 w=320 h=240 float=center]
Because this is a custom list, we choose a validation type of List Validation, and a value format of L, indicating that any letters are allowed. For a full list of these conventions, refer to the help documentation in the system by pressing F1.
[singlepic id=291 w=320 h=240 float=center]
[singlepic id=292 w=320 h=240 float=center]
We finalize the set-up of the field by indicating:
- Field naming conventions: Compiere recommends that customer-specific table and database column names be prefixed by EXT_, XX_, or CUST_, or the four letter entity registered with Compiere, such as SAAC_. This would also apply to indexes and constraints. The reason for this is that these entities are ignored in the migration process.
- Length of field: Because we know that for this particular field there is going to be only one character we define a length of 1.
- Default logic: We assume U, based on our list being Unknown.
- Mandatory UI: Indicates that this field will be mandatory in the window, but not at database level.
- Updatable: Indicates that the field is editable.
- Always Updatable: Indicates that the field is always updatable, regardless of document status.
Final step in column creation—Create / Synchronize with the database
The final step in the process of creating a field is to make sure that it is synchronized to the underlying database from the AD. Scroll down on the column tab to find the Synchronize Column button, as shown in the example below:
[singlepic id=293 w=320 h=240 float=center]
Adding our custom field to the Order window
Back in the menu item Window, Tab, and Field (find the Sales Order window) > Tab (header/top level):
- Click on the Create Fields button to add the field to the database:
- Change the desired sequence of the field to the correct position in the list of fields:
- Re-open the appropriate Sales Order window to display the field:
- A workflow is made up of a node and transitions.
- A node refers to a piece of work.
- A transition is the action to get to the next node, based on a logical condition.
- The workflow process is the active workflow and an activity for the processing of the active node (an activity also may have multiple parallel processes).
- A workflow also has an active State. A Workflow State refers to whether the workflow is running, not running, not started, completed, aborted, or terminated.
- Nodes also have Owners or Responsible persons.
- Open the Workflow editor window, and find the Order process Process_Order. Right-click in the editor, and then add an additional new node called Order Approval:
- We need to define where the transition is going to take place by defining the originating node (Document prepare) and the next node (Document complete):
- Click on the upper-right Zoom button to zoom to the actual workflow process, and find the newly-created node:
- Define the node's owner by creating a workflow owner. Right-click on the workflow owner field:
- The node's workflow owner is set to be role-based, as follows:
- The Node for Approval can be summarized as follows:
- Define the Transition of the node through a condition:
- We log in as the GardenWorld Purchasing role, as follows:
- Create a Purchase Order, and then click on the Complete button. The Order will be placed in an In Progress status, because the workflow's next node is document approval:
- We log off, and then log back in to the system with the GardenWorld User role (workflow owner):
- Find the Workflow Activities menu item, and then approve the document, as follows:
- The Document will be approved when the owner sets the approval status to Yes:
- We gave you an overview of the Compiere Application Dictionary components.
- We illustrated how to add a menu item and a custom list field to a Compiere window by using the AD components.
- We gave you an overview of the Compiere Workflow processes, and illustrated how this is set up.
[singlepic id=294 w=320 h=240 float=center]
[singlepic id=295 w=320 h=240 float=center]
[singlepic id=296 w=320 h=240 float=center]
Setting Up a Basic Document Workflow in Compiere 3
Compiere's workflow processes form an integral part of the system. In this section we are going to learn how to setup a basic approval workflow for a document within Compiere.
The system definitions are as follows:
[singlepic id=297 w=320 h=240 float=center]
Illustrative workflow example
We are going to set up a workflow between two roles, whereby the Gardenworld Purchasing role will capture a Purchase Order and the order will be approved by the Gardenworld User role. This type of approval requires a flag, and Compiere has a built in IsApproved database field that is used for this purpose.
Compiere has standard document workflows and transitions that are predefined within its workflow processes. These nodes are DocStart, DocPrepare, DocComplete, and DocAuto (automatic approval). What this means is that workflow processes already manage the transitions of documents, with the System being the Owner of these workflow nodes.
Defining a custom node in a workflow
We use the workflow editor to define a new node.
[singlepic id=298 w=320 h=240 float=center]
[singlepic id=299 w=320 h=240 float=center]
[singlepic id=300 w=320 h=240 float=center]
[singlepic id=301 w=320 h=240 float=center]
[singlepic id=302 w=320 h=240 float=center]
[singlepic id=303 w=320 h=240 float=center]
[singlepic id=304 w=320 h=240 float=center]
The condition we set up for the document workflow to transition to Document Complete is as follows:
[singlepic id=305 w=320 h=240 float=center]
Testing the workflow
We can now illustrate the workflow by creating an order and ensuring that it gets approved correctly.
[singlepic id=306 w=320 h=240 float=center]
[singlepic id=307 w=320 h=240 float=center]
[singlepic id=308 w=320 h=240 float=center]
[singlepic id=309 w=320 h=240 float=center]
[singlepic id=310 w=320 h=240 float=center]
Summary
We have covered certain aspects with regards to Compiere in this three-part article series—namely the Application Dictionary (AD) and Workflows, as follows:
