ADempiere 3.4 ERP Solutions: Implementing an Enterprise Resource Planning (ERP) system in your organization can be a smooth process when you follow this ADempiere tutorial. From understanding the basics to customizing for your own needs, it's a great intro to an excellent system.

ADempiere can be installed on any operating system—Mac OS, Linux, BSD families, and so on, but in this book we will use Microsoft Windows as the operating system.

You can download the latest JDK/JRE available from the Sun Microsystems website at http://java.sun.com/. Throughout this book, JDK 5.0 will be used as a prerequisite for installing ADempiere. We can download JDK 5.0 from http://java.sun.com/javase/downloads/index_jdk5.jsp. At the time of writing this book, the latest version or release for JDK 5.0 is JDK 5.0 Update 17. Future versions or releases of JDK can also be used without any problems.

Click on the JDK 5.0 Update 17 Download button, and you will be directed to the download page. Set the platform as Windows and the language as Multi-Language. On the next page, choose Windows Offline Installation. The filename for this JDK is jdk-1_5_0_17-windows-i586-p.exe. It is about 52.15 MB in size. In order to manage the downloaded files, first create a C:\download\jdk folder, and then save the files to this folder.

JDK installation files are required for the ADempiere server installation, but they are not necessary for the ADempiere client installation. On the client side, only the JRE installation files are needed. To download these files, click on the Java Runtime Environment (JRE) 5.0 Update 17 Download button. Select the platform and language as mentioned previously, (including the Windows Offline Installation mode). Save the jre-1_5_0_17-windows-i586-p.exe file to the C:\download\jdk folder.

Due to the default installation behavior of Microsoft Windows, a new application installation will commonly be directed to the C:\Program Files folder. An important thing when installing JDK and/or JRE on Microsoft Windows is that we should avoid installing it to C:\Program Files directly. To avoid any problems during the ADempiere implementation, it is recommended that you install it to a folder that does not contain spaces in the directory or folder name, such as C:\Java.

JDK installation on the ADempiere server computer

Double-click on jdk-1_5_0_17-windows-i586-p.exe to start the Windows installer.

By default, the installer will install development tools, demo files, source code, and public JRE. For our reference, leave the Development Tools feature selected and deselect the other features by clicking on the buttons on the left-hand side of Demos, Source Code, and Public JRE, and then choosing Don't install this feature now. This is shown in the following screenshot:

Select Development Tools, click on the Change button to alter the default or target directory to C:\Java\jdk1.5.0_17, and proceed to complete the JDK installation.

Note

During the Development Tools installation, a private JRE will automatically be installed. In our case, it will be installed at C:\Java\jdk1.5.0_17\jre.

JRE installation on the ADempiere client computer

The ADempiere client installation requires installation of the Java Runtime Environment (JRE) only. Open the link http://java.sun.com/products/archive/j2se/5.0_17/ and double-click on jre-1_5_0_17-windows-i586-p.exe. At the license agreement, ensure that you choose the Custom setup, and click on the Accept button. Leave the J2SE Runtime Environment selected, and deselect the other features by clicking on the buttons to the left-hand side of Support for Additional Languages and Additional Font and Media Support. Choose Don't install this feature now. Select J2SE Runtime Environment, click on the Change button to alter the default or target directory to C:\Java\jre1.5.0_17, click on the Next button, and proceed to complete the JRE installation.

Tip

There is no need to install JRE if you are using the same computer for both the ADempiere Server and the Client.

Now that we have installed JDK/JRE, we have to set up JAVA system variables and set Windows paths both for the ADempiere server and the client computer, as ADempiere runs on a Java platform.

We need to set these variables in the System Properties window. You can access this window through Start | Control Panel | System (or Start | Settings | Control Panel | System in the case of the Windows classic menu). Select the Advanced system settings tab, and click on the Environment Variables button.

The following table shows the value of a Java system variable and a Windows path for the ADempiere server installation to be set up in the Environment Variables window:

For the ADempiere client installation, you may set the following Java system variable and Windows path in the Environment Variables window:

The Environment Variables window is shown as follows:

This is an example of System variables in the Environment Variable window from the author's computer. It might vary for your own computer's configuration.

You can set additional JAVA_HOME variables by clicking on the New button in System variables. To set your own JAVA_HOME variables, click on the Edit button by selecting an existing path variable entry and enter your additional path entries. In order to confirm the addition of system variables, click on OK in both the Environment Variable window and the System Properties window.

Once we have finished adding the additional variables, we have to check whether the setup of the variables was configured properly. We shall check our variables' entries from the DOS prompt command line. We can access DOS prompt from Start | Run. Type cmd in the Run window, and click on the OK button. We will get the following command prompt:

We can type the following in this command line, and Enter:

C:\>SET

Pay attention to the resulting information. On the author's ADempiere server computer, it displays the following statements:

JAVA_HOME=C:\Java\jdk1.5.0_17

and

Path=C:\WINDOWS\system32;C:\WINDOWS;C:\WINDOWS\System32\Wbem;C:\Java\jdk1.5.0_17\bin;C:\Java\jdk1.5.0_17\jre\bin\client

Whereas the ADempiere client computer will contain the following statements:

JAVA_HOME=C:\Java\jre1.5.0_17

and

Path=C:\WINDOWS\system32;C:\WINDOWS;C:\WINDOWS\System32\Wbem;C:\Java\jre1.5.0_17\bin;C:\Java\jre1.5.0_17\bin\client

The second procedure for checking the setup configuration is to use Java commands. For example, in order to find a command to know what the currently-installed Java version is, we can use the following command:

C:\>java -version

and press Enter. This showed the following statements on the author's computer:

java version "1.5.0_17"Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_17-b04)Java HotSpot(TM) Client VM (build 1.5.0_17-b04, mixed mode, sharing)

We can obtain PostgreSQL databases for Microsoft Windows from http://www.postgresql.org/download/windows. You will find an option to Download the one click installer or pgInstaller. Click on Download the one click installer, and you will be redirected to the Enterprise DB website: http://www.enterprisedb.com/products/pgdownload.do#windows. Download the installer for the Microsoft Windows operating system.

At the time of writing, the latest release of the PostgreSQL database for Windows is PostgreSQL 8.3.5. After we click on the download button on this site, we will be prompted to save the postgresql-8.3.5-2-windows.exe file (about 35.7 MB in size). Create a C:\download\database folder, and save this binary installation file to this location.

Double-click on the postgresql-8.3.5-2-windows.exe file to launch the Windows installer. During the installation, this installer will install additional required files for us automatically. It will install Microsoft Visual C++ 2005 Redistributable. When asked for the installation directory, point it to C:\download\database\postgresql\8.3, instead of the default installation directory, as shown in the following screenshot:

Click on Next, and you will be prompted with the data directory location confirmation. You can define your own data directory or location. On the author's computer, the data directory is left as it is—C:\download\database\PostgreSQL\8.3\data. Next, set a password for your Postgres account. In this installation, we use postgres as the default password for the Postgres account.

Leave the default Port used for this database as 5432, set Locale to English, United States, and proceed to complete your database installation.

On the final installation screen, you need to deselect the Launch Stack Builder at exit option.

The PostgreSQL database server for ADempiere has been successfully installed. During ADempiere installation, there are many PostgreSQL application tools (*.exe files) that can help you to manage your database. Most of these tools can be found in the %PostgreSQLHome%\bin folder.

Examples of these application tools are given in the following table:

These tools will be used throughout this book. In order to add these folders to our Path System variables, do the following:

Just like we verified the Java system variables, we should verify our PostgreSQL path. Previously, we used the SET command to accomplish this task. We shall use the path command to verify the path.

Open the DOS prompt command-line window and type:

C:\>path

Press Enter, and the system will display the current computer PATH. Ensure that we have C:\database\PostgreSQL\8.3\bin in the contents of PATH. The following is the screenshot from the author's computer:

The next procedure is to verify the additional PostgreSQL paths. Type the psql command on the command line, and press Enter. If we are prompted to enter a password, then our PostgreSQL path setting is working as expected. Press Enter, and the system will display the following information:

psql: fe_sendauth: no password supplied

Thus, we have completed the database installation and verification.

By default, the initial security configuration settings to access PostgreSQL databases are quite restrictive. This is a good practice as we can make sure that our databases can be accessed from trusted computers only. We can define an additional list of computers that can access our databases by altering some PostgreSQL configuration files.

Modifying the client authentication configuration file

The name of the client authentication configuration file is pg_hba.conf. It can be found in the %PostgreSQLHome%\data folder. This file contains the information shown in the following screenshot:

With this configuration, the database connection is accepted from a local computer only. If we wish to allow any computer within our local LAN, which is pre-installed with the ADempiere client—and let us assume that our computer server has a 10.10.101.107 IP address—then we should add the following two lines of configuration:

host adempiere adempiere 10.10.101.107/0 md5
host template1 postgres 10.10.101.107/0 md5

to our pg_hba.conf file.

Tip

The 10.10.101.107/0 defines the IP and subnet masks allowed. Visit http://en.wikipedia.org/wiki/Subnetwork for a further explanation.

listen_addresses = '*'

For security reasons, the current Microsoft Windows installation's best practice is to block all incoming connections to unrecognized ports. We need to tell Microsoft Windows which port is being used by the PostgreSQL database by default.

During our PostgreSQL database installation, we used port 5432 as the standard database communication port on all of the connected computers within our network (including the host or database server itself). We will open this port from the Windows firewall, which can be accessed from Start | Control Panel | Windows Firewall.

Select the Exception tab, and click on the Add port button. Complete the PostgreSQL Name field, and enter 5432 as the Port number. Ensure that you select TCP instead of UDP. Click on the OK button.

Currently, all of the ADempiere binary files, source code, and any other files related to ADempiere are hosted at http://sourceforge.net/. Throughout this book, we will use ADempiere 3.4.2s (as the latest stable version for the 3.4 release series).

We can download this file from http://downloads.sourceforge.net/adempiere/Adempiere_342s.zip. The installation file is about 99.22 MB. Create the C:\download\adempiere folder, and save the file to this folder.

For checking the integrity of our ADempiere installer, we will download its MD5 signature. Download the MD5 signature for ADempiere_342s.zip from http://sourceforge.net/projects/adempiere/files/Adempiere_342s.zip.MD5.

The ADempiere version 342s was released on December 21st, 2008. After the first release, there has always been an effort to fix bugs, and the ADempiere developer community has released regular application patch files. Along with these application patch files, sometimes the community provides files that need to be applied to the ADempiere database, too. We call these files, as migration script files which aim to alter the ADempiere database and make it comply with a newer database structure.

Obtaining the ADempiere application patch files

ADempiere developer community releases their patch files in the following format:

No	Format name	Description
1	patches_xxxx_yyyymmdd.jar	ADempiere core patches for version xxxx and released on the year, month, and date mentioned in patch's filename
2	zkpatches_xxxx_yyyymmdd.jar	ADempiere ZK web user interface patches for version xxxx and released on the year, month, and date mentioned in patch's filename

We can obtain a list of available ADempiere patch files from http://sourceforge.net/project/showfiles.php?group_id=176962&package_id=230906&release_id=648627. Here is an example of a list of ADempiere patch files that are currently available:

Note

For patch files, we need the latest files for both ADempiere core and the ADempiere ZK web user interface.

With this information, we shall download patches_342s_20091110.jar and zkpatches_342s_20091110.jar. For verification purposes, we shall download patches_342s_20091110.jar.MD5 and zkpatches_342s_20091110.jar.MD5 also. Put all of the downloaded files in the C:\download\adempiere folder.

While downloading, due to the uncertainty of Internet connections, sometimes our download files remain in an incomplete state. On the other hand, if we download the binary file from an unknown site, there is a possibility that it might be modified by somebody out there who wants to introduce security holes! This can lead to an unrecognized behavior when trying to proceed further with this file.

To avoid any unnecessary headaches in the near future, we strongly recommend that you perform an integrity check and validate your ADempiere binary installation files.

ADempiere provides us with MD5 signature files on the SourceForge sites. MD5 is one of cryptographic methods that can be used for verifying the integrity of files.

For a complete explanation of MD5, you can read http://en.wikipedia.org/wiki/MD5.

Fortunately, there are a lot of free tools that can be used to help us check the validity of files. One of them is Mat-MD5 (http://www.matsoftware.it/software/mat-md5). Create the C:\download\tools folder, and then download this tool into this folder.

We will now proceed to check the integrity of all of our ADempiere binary files, including core files and patch files. As an example, we will try to verify our ADempiere_342s.zip files, by performing the following steps:

If everything goes well, the system will indicate a successful integrity check, as shown in the following screenshot:

Otherwise, we need to download the ADempiere binary files again from http://sourceforge.net/ and perform another integrity check until the files are successfully verified.

The ADempiere core installation file is Adempiere_342s.zip. This is only a ZIP file and not a windows installer. We need to extract the content of the ZIP file to the C:\ drive. Navigate to the C:\download\adempiere folder, right-click on this file, and click on Extract All. When the system asks about the target directory, point it to the C:\ drive. Click on the Next button to extract the files. Your ADempiere files should be found in the C:\Adempiere folder. The standard ADempiere folder structure is shown in the following screenshot:

Applying patch files is an easy task. First, ensure that you back up your patches_342s_20091110.jar and zkpatches_342s_20091110.jar files by copying them to the C:\download\adempiere\backup folder. Rename the original files in the downloaded folder from patches_342s_20091110.jar to patches.jar and from zkpatches_342s_20091110.jar to zkpatches.jar.

Before copying the patch files to another folder, it's a good practice to keep a backup of the original C:\adempiere\lib\patches.jar and C:\adempiere\lib\zkpatches.jar files. We shall put these backup files into the C:\download\adempiere\backup folder as well. The last thing to do is to copy our downloaded patches.jar and zkpatches.jar files, which can be found at C:\download\adempiere, into the C:\adempiere\lib folder.

During the copying procedure, when the system prompts us with a Confirm File Replace question, just click on Yes to All, and we will have finished our tasks.

ADempiere provides us with an initialized database dump. This file contains a list of SQL commands that can be used to create the ADempiere database structure and predefined data. The physical name of this file is Adempiere_pg.dmp. We will find this file in the C:\Adempiere\data folder.

Creating a PostgreSQL new login role

While configuring the ADempiere server, a special login role is required, which is used internally by ADempiere. We can define additional login roles by using the pgAdmin III tools. We can access these tools through Start | All Programs | PostgreSQL 8.3 | pgAdmin III.

Double-click on PostgreSQL 8.3 (localhost:5432) in Object browser to connect to the PostgreSQL database server. When the system prompts us with the Connect to Server window, we will supply our postgres account password and click on OK.

Note

During the PostgreSQL databases installation, we provided postgres as our postgres account password.

After successfully logging in by using this tool, the system will show a screen similar to the following screenshot:

In order to add a new login role, right-click on the Login Roles node, and click on New Login Role. Create the role name adempiere with the password adempiere, and ensure that the following Role Privileges are selected:

• Superuser

• Can create database objects

• Can create roles

• Can modify catalog directly

Tip

This role name is the user who was previously configured in the Modify client authentication configuration file section.

ADempiere needs to be configured on the server side. This task is intended to notify ADempiere about predefined variables or information. This information is needed by ADempiere to integrate the database, to bind official ADempiere core patches and ZK web user interface patches to the ADempiere core application, and to host these core packages on their default embedded application server (JBoss).

Double-click on the run_setup.bat file, which can be found in the C:\Adempiere folder. We need to complete the fields using the information given in the following table:

Leave the other fields unchanged. Click on the Test button in the Adempiere Server Setup window. When the system prompts you with the Key Store Dialog window, complete the fields with your information, and ensure that the setup window displays an Ok message on the bottom-left info bar, as shown in the following screenshot:

Click on Save to proceed with our ADempiere server installation configuration. Carefully read through the ADempiere license agreement window. Accept the terms of the agreement, and click on OK once again to start the ADempiere deployment. Wait for a moment as the ADempiere system performs its internal tasks to configure and build our ADempiere server.

At the end of these tasks, we will get the information shown in the next screenshot, which indicates successful packaging and deployment of the application to the embedded JBoss application server.

As mentioned earlier, the ADempiere developer community will release their patches regularly. If there are newer patches available, you can download those patch files, perform MD5 verification, copy them to the C:\Adempiere\lib folder, and then run run_setup.bat again.

We need to import the structures such as tables, functions, initial data, and another prerequisite metadata into our blank ADempiere database previously created. ADempiere provides us with a script or batch file to load Adempiere_pg.dmp into our blank ADempiere database.

Find and execute RUN_ImportAdempiere.bat, which can be found in the C:\Adempiere\utils folder. During execution, this script will show you a message, as shown in the next screenshot:

Press Enter, and the import activity will run immediately.

psql: FATAL database "adempiere" does not exist

Although it lists the Adempiere.dmp file with our configuration value while executing run_setup.bat, this batch file should load and import the Adempiere_pg.dmp file.

psql -U adempiere -f 372_round.sql -o 372.txt
psql -U adempiere -f 379_FR1883270_NextIdByYear.sql -o 379.txt
psql -U adempiere -f 391_C_Currency_Rate.sql -o 391.txt
psql -U adempiere -f 398_currencyround.sql -o 398.txt
psql -U adempiere -f 413_BF2567104.sql -o 413.txt
psql -U adempiere -f 417_FR2582181.sql -o 417.txt
psql -U adempiere -f 436_MissingSysConfigKeys.sql -o 436.txt
psql -U adempiere -f 441_BF2710889_Add_Months.sql -o 441.txt
psql -U adempiere -f 442_BF2710889_PaymentTermDueDate.sql -o 442.txt
psql -U adempiere -f 443_BF2714803_InvoicepaidToDate.sql -o 443.txt
psql -U adempiere -f 444_BF2714831_InvoiceopenToDate.sql -o 444.txt
psql -U adempiere -f 566_FR1756793_RMA_JUST_FOR_343.sql -o 566.txt

We can check the physical memory available by opening Windows Task Manager. Use the shortcut keys Ctrl + Shift + Esc. Click on the Performance tab and you will see the Physical Memory (K) information, as shown in the following screenshot:

This shows that the author's computer has 2086956 kilobytes (almost 2 GB) of physical memory.

During the initial loading of the ADempiere application server, the system will allocate a minimum memory for its operations, and if necessary, it will allocate more memory resources until it reaches the maximum value specified by the configuration. We can access this configuration from the myEnvironment.bat file in the C:\Adempiere\utils folder.

If you go through this file, then you will find the following information:

@SET ADEMPIERE_JAVA_OPTIONS=-Xms64M -Xmx512M -DADEMPIERE_HOME=C:\Adempiere

With this default configuration, ADempiere will consume 64 MB of available memory (-Xms64M) during the initial loading. If required, the maximum memory could be allocated, that is, 512 MB (-Xmx512M).

We are not discussing how to perform efficient memory allocation. We are just ensuring that we have allocated the maximum memory, that is, 75 percent of our memory available.

With this requirement, we can set this configuration as follows:

@SET ADEMPIERE_JAVA_OPTIONS=-Xms256M -Xmx512M -DADEMPIERE_HOME=C:\Adempiere

This means that we will allocate a maximum of 512 MB of memory from the available memory of 1406 MB on the author's computer.

On the server side, we need to start our application server. To start the application server, double-click on Run_Server2.bat in the C:\Adempiere\utils folder.

Check the DOS Prompt, and wait for a while, until you see a notification such as the following:

12:31:52,564 INFO [Server] JBoss (MX MicroKernel) [4.0.2 (build: CVSTag=JBoss_4_0_2 date=200505022023)] Started in 1m:48s:637ms

Now our application server is ready.

Starting the application server will start ADempiere's accounting processors, internal schedulers, ADempiere's web user interface, ADempiere's web admin tools (that can be used to install ADempiere client), ADempiere's client Web Start feature, and all of the activities related to the ADempiere server.

After we finish our work with the ADempiere server, we have to shut down the application server. We can shut it down by double-clicking on Run_Server2Stop.bat in the C:\Adempiere\utils folder.

This is the easiest way to install the ADempiere client on a client computer. Click on Click Here to WebStart Me Now!, and the installation process starts automatically.

While accessing Web Start for the first time, the system will download the application from the ADempiere server, perform verification of the application, and launch the ADempiere client application itself.

The system will check the latest client application configuration on the server side, before launching ADempiere client application the next time. If there are updates available, then the system will download the application again and launch the latest client application. With these features, all clients connected to the server will always use the updated ADempiere client application.

Before using the ADempiere client application, we need to verify the ADempiere client connection through the ADempiere application server. Launch the Web Start application by double-clicking on the previously-created shortcut. The system will prompt us with the Adempiere License Agreement window. Read it carefully, and accept the license.

This opens the Adempiere Connection window. Here, you need to change the following information:

Leave the other fields unchanged. For example, on the author's computer, the application host is 10.10.101.107.

Click on the Test Application Server button, followed by a click on Test Database. Ensure that both buttons result in a green check mark, as shown in the following screenshot:

If you click on the Ok button (green check mark) on the bottom right-hand side of the window, then you will be directed to the ADempiere login window. For now, click on the Cancel button, and we are done.