ADempiere Technical Training

Completion status: this resource is ~50% complete.

Type classification: this resource is a course.

Type classification: this is a lesson plan resource.

Type classification: this is a workshop resource.

Subject classification: this is an information technology resource.

Introduction

Subject Matter Expert and course creator is Carlos Ruiz, Head of the Project Management Committee during the first four years of the project ADempiere.

History

ADempiere's parent project, Compiere started as a premier first-class Open Source ERP. With a design history since 1982, Compiere development was sponsored in 2000 by Goodyear in Germany. Its creator - Jorg Janke - has a strong background in ERP, SAP, Oracle, Active Dictionary, Java and Financials. Compiere is an italian name that stands for “to accomplish, fulfill”. It made its debut as a an Open Source project in SourceForge.net in June, 2001 and received venture capital funding sometime early 2006.

After 5 months without fresh code release, privately announced changes in support contracts, and unreplied queries in the forums, in September 2006 the large gathered community concerned about commercial pressures to make Compiere closed, started an intense public discussion about forking the project and finally concluded in a new project called ADempiere that has added meaning of 'to fulfill completely'. The evolution of the project is fast – in a bit over 100 days ADempiere hit number 1 in SourceForge surpassing even the earlier fork but another commercial enterprise - OpenBravo ERP.

The core goals of ADempiere are, to keep releasing improved but stable versions, remove any proprietary stack, without too much functionality added. This goal was accomplished on May 1st, 2007 – with pleasant new features such as postgresql porting, oracle-XE support, new facelift, migration tool, performance enhancements, lots of bugs fixed, 2pack importer/exporter tool, a Wiki site for community contributed documentation, Jasper integration, added extensibility in model validator and many different localizations such as German, Thai, Russian, Spanish (Latin America), Brazilian Portuguese and Indonesian. Its growth is now set for good, with a constant influx of contributions and over a 100 declared installations. In short it differentiates itself by being a de-facto community open source ERP project.

Organization

ADempiere is a community oriented project.
Not owned by any company.
Council: group of 9 founders
Leader: council founders voted for a Leader - Redhuan Daniel Oon – Malaysia. Compiere online tutor since July, 2004
Business Development Committee (BDC): This is a 4 member Committee whose purpose is to give a welcome to the businesses interested in the project.
Project Management Committee (PMC): This is a 8 member Committee to provide guidance and direction to the project
PMC Head: Carlos Ruiz - Colombia
Committers (formerly Commit Committee CC): Currently there are 15 Committers allowed for 1st layer access. Many others (50+) are of 2nd layer requiring more peer support in final commit decision.
Commiters' Head: Low Heng Sin – Malaysia
Community: In many cases the community is consulted to vote through forums for decisions.

Architecture

ADempiere has a very good architecture (inherited from Compiere), it is designed with the intention of following changes as business evolves. At any time, customers can change the information structure, adjusting to new information needs.

Model-View-Controller
Active Data Dictionary
Multi-tenant
The multi(s) – (organization, currency, accounting, costing, language, taxes)

Useful utilities & Accessories

ADempiere also inherited from Compiere very useful utilities and accessories such as:

Embedded Log4J for debugging purpose
Jboss Application Server deployment
Compiler and Installer routines
DB Backup and Restore routines

Subject Matter Expert/Trainer

Carlos Ruiz, Colombia, with courses in California, Colombia, Argentina, Nicaragua, Spain, Venezuela, Uruguay, Ecuador

Installation

Below is a consolidation of ADempiere's project wiki: [1].

Prerequisites

Java JDK 1.5 (for version 3.4.2s), Java JDK 1.6 for version >= 3.5.3a
Supported Databases:
- Postgresql 8.x
- Oracle 10G/11G (supports also XE version)

Build

This step is not needed if you download a ready to install version – release or nightly build.

Download the source code from the sourceforge subversion repository:
http://adempiere.svn.sourceforge.net/svnroot/adempiere/trunk

There are also provided tags and branches if you want to download and build a different version.
After downloading the sources with a subversion client (i.e. Download in C:\srcAdempiere\trunk) you need to edit the file utils_dev/mybuild.properties (this file can be copied from utils_dev/build.properties) and set the following variables (you need to replace the directories to those for your environment):

1. env.ADEMPIERE_SOURCE=C:/srcAdempiere/makeinstaller
2. env.ADEMPIERE_ROOT=C:/
3. env.ADEMPIERE_HOME=C:/Adempiere
4. env.ADEMPIERE_INSTALL=C:/srcAdempiere/Installers
5. env.ADEMPIERE_VERSION=ADempiere
6. env.ADEMPIERE_VERSION_FILE=Trunk
7. env.ADEMPIERE_VENDOR=ADempiere
8. env.ENCODING=UTF-8
9. env.XDOCLET_HOME=${env.ADEMPIERE_SOURCE}/tools
10. env.ADEMPIERE_ENV=Y

In the above file,

- line 1 is set to your source directory where you have downloaded the SVN source. 

- line 2 is set to your SVN source disk root for example C:\ D:\ or /usr etc

- line 3 is where adempiere install files are written to. In other words if this 

         directory does not exist, the build process will create it.

- line 4 is where your SVN Source is and build process will create an 'Installers' 

         folder under this directory. It is not necessary to have this line point to SVN 

         source directory instead it can be pointed to any other directory where you want your 

         zipped up version of installer files are to be created. These zipped version is equivalant

         to line 2 directory content.

- line 5 thru line 10 can be left at default values.

After setting up the file you can run the script utils_dev/RUN_build (.bat for windows or .sh for linux).
This process will create installer files in the env.ADEMPIERE_INSTALL configured directory:

Adempiere_Trunk.tar.gz – gzipped tar for linux installation
Adempiere_Trunk.tar.gz.MD5 – md5 checksum for the gzipped tar file
Adempiere_Trunk.zip – zipped file for windows installation
Adempiere_Trunk.zip.MD5 – md5 checksum for the zipped file

You can use gzipped tar or zipped file in any environment – you just need to have the needed decompressing tool. The script also decompress the file in the directory configured as ADEMPIERE_HOME.

Exercise: Download trunk, a tagged version or a branch (copy from CD or server) and build Adempiere installers

Server Installation

First you need to set up two environment variables: ADEMPIERE_HOME and JAVA_HOME, i.e.:

SET ADEMPIERE_HOME=C:\Adempiere
SET JAVA_HOME=C:\Program Files\Java\jdk1.5.0_11

Once the prerequisites are installed and tested the installation is straightforward.

Uncompress Adempiere

Setup the installation

C:\Adempiere\RUN_Setup (.bat or .sh) to setup the adempiere (application-)server.

C:\Adempiere\utils\RUN_ImportAdempiere (.bat or .sh) to import initial adempiere data into your database (as specified in RUN_Setup).

HINT: If you're reinstalling and have a previous backup ExpDat.dmp you can use RUN_DBRestore (bat or .sh) instead

If everything went right you can start the server:

RUN_Server2

The most important part of the installation is to fill properly the RUN_Setup parameters.

RUN_Setup creates Adempiere.properties (server environment) and AdempiereEnv.properties (Environment info) – these files must be secured, they contain sensitive information

Finally, please note the RUN_Server2 leaves a session box opened (command line box).
To avoid this you would need to install adempiere as service:
in windows using the provided tools for %ADEMPIERE_HOME%\utils\windows
in linux using the tools on $ADEMPIERE_HOME/utils/unix

DB and application server can be installed in one single server.
Optionally you can install DB in one server, and application in other server.

Exercise: Install server and verify execution

Installed Services

After Adempiere is installed you find the following services by default:

Web UI (Beta) : http://machine:port/adempiere/
Initial page: http://machine:port/admin/
System Monitor: http://machine:port/admin/adempiereMonitor
Web Store: http://machine:port/wstore
Web POS (POSterita): http://machine:port/posterita/
JMX Console: http://machine:port/jmx-console

When you find conflict with ports (i.e. port 80 already used by apache - or port 8080 already used by oracle), you can find information about the program using the port with

netstat -a -o

then you can find the PID in task manager

For configuration of the log you can customize the file C:\Adempiere\jboss\server\adempiere\conf\log4j.xml

Apache

It's recommended to install apache as proxy or mod_jk (Apache Tomcat Connector) server for adempiere. Ports used by default:

Web – 80
SSL – 443
JNP (RMI) – 1098 (1099)
AJP13 (mod_jk) – 8009
Class loader – 8083

Client deployment

After installation and with the server running, you can download and install the clients from the website and port configured in RUN_Setup, i.e.:

http://machine:port/admin

ZIP Method: Download and install the client zip file

Webstart method (recommended): push the “Click Here to WebStart Me Now!” button. This is the recommended method – webstart transparently deploy changes for clients when needed.

If you want to connect to different environments (i.e. development, test, production), you can change the property file, i.e.:

-DPropertyFile=AdempiereProduction.properties

Or change the parameter in the file RUN_Adempiere

NOTE: Webstart property file can't be changed in the client.

Troubleshooting

Java 6 can be used to run the clients but not for compiling (for 3.4.2s)
Installing PL/java requires a PATH trick in windows (described in adempiere wiki)
Installing PL/java in linux requires to compile the latest pl/java version from cvs, and manual installation requires lots of troubleshooting dynamic libraries and postgres configuration.
Troubleshoot firewalls if you can't connect from clients
If webstart have problems when creating the shortcut link in desktop try the alternate method: “try this“
WAN connection

Application Dictionary

This is a huge topic and we have put it here at ADempiere Application Dictionary for the ease of those who access this resource via mobile or weak lines.
You can read some history and overall context of the Application Dictionary here.

Administrative Tasks

Creating a New Client

Configuring security

There are various levels of security. One is via Single Sign-On to restrict access to authorized users. Another is via Role-based control.

For every role you can configure (enable / disable / read-only) access for:

Organization
Windows
Processes
Forms
Workflows
Tasks
Tables
Columns
Records

Then you assign roles to users. Every user can have several roles, but must select one of the assigned roles at login time.

Auditing

Auditing is powerful in Adempiere. You can configure audit option to roles (Maintain Change Log) or for Tables.

Also by default there is a complete audit for sessions, process and workflow executions.

Backups

You can take database backups with the provided script in $ADEMPIERE_HOME/utils/RUN_DBExport (.bat or .sh) It is encouraged to program backups to be executed automatically and periodically.

RULE OF THUMB: Test your backups

Other advanced server/oracle/postgres tools can be used depending on the acceptable level of data loss. I.e.: RAID, RMAN, replication ...

Performance

Every installation has his specific needs for performance tuning.

Some tips can help with tuning tasks:

Big non-transaction tables: create index with (AD_Org_ID, AD_Client_ID, IsActive)
Big non-transaction tables: create index with (UPPER(Value))
Big non-transaction tables: create index with (UPPER(Name))
Big transaction tables: create index with (AD_Org_ID, AD_Client_ID, DocStatus, Processed, Posted)
Separate index, data and blob tablespaces

2pack

One of the most difficult problems implementors had in Compiere was to translate changes between the different environments (i.e. Development to Testing, or Testing to Production).

2pack extension is intended to ease this transfer between environments.

2pack Export

In the origin environment you need to define a package and export it (PackOut window). In a package you can define/export:

Menu (when you select a menu all the children associated objects are exported, this is windows, tabs, fields, tables, columns, references, etc)
Code Snippet
Data
Dynamic Validation Rules
Files
Form definition
Import Format
Message
Print Format
Process/Report definition
Report View
Role
Execute SQL Statements
Table, columns definition
Window, tab, field definition
Workbench definition
Workflow definition

After you define the package you simply need to push the “Export Package” button and a zip file will be constructed with the corresponding data packaged in a XML file.

2pack Import

In the target environment you need to define the package import (PackIn window) and run the “PackIn” process. 2Pack will create all needed objects in the target environment.

Code

SVN Structure

trunk – most recent status of development – in Adempiere project there are strict rules to keep the trunk stable (at least compilable)

branches – experimental (libero), stable version support (adempiere321, patches_321)

tags – read-only repository of tagged versions

contributions – all other stuff (localizations, POC, tools, etc)

nightly build

Eclipse setup (one big project)

It is recommended you group your related projects using Working Sets in eclipse.

You can set up adempiere as a one big project, for this simply point your project to the root of adempiere, i.e.:

trunk
branches/adempiere321
tags/adempiere320

This is easier to set up, but you can miss possible dependency problems. They'll appear just when compiling finally with RUN_build.

Eclipse setup (several projects)

Another way to set up eclipse is creating a project for each adempiere directory, i.e. you download trunk and one project for each:

base
client
data
db
doc
extend
extension
install
interfaces
JasperReports
JasperReportsTools
JasperReportsWebApp
jboss
launch
lib
looks
migration
packages
posterita
print
serverApps
serverRoot
sqlj
tools
utils
utils_dev
webCM
webStore

This way to set up eclipse is more difficult - but you'll see dependency problems within eclipse.

Project Customization Management Hints

The recommended set up for projects is:

create one-big eclipse project with last stable version (or the version you're implementing)
create one eclipse project with the patches project for that version (if exists)
create one eclipse project with the customized classes for your project

i.e.

adempiere320 - from https://adempiere.svn.sourceforge.net/svnroot/adempiere/tags/adempiere320
patches_321 - from https://adempiere.svn.sourceforge.net/svnroot/adempiere/branches/patches_321
your_project - from your own svn or cvs repository

You must not change adempiere320 classes - they are the tagged version.

You must not change patches_321 classes - they are officially released from Adempiere community - unless you're a committer of adempiere project fixing problems with the version

You can create/change your project classes following these suggested guidelines:

More: [2]

Customizing core classes

If you need to customize a core class, please copy the java file from adempiere320 or patches_321 into the custom project with the same directory structure.

For example, if you need to customize CalloutPayment.java, you must copy it from adempiere320 to the trunk of the custom project in the folder base/src/org/compiere/model

IMPORTANT: Please take account if your change is fixing a bug, or a contribution worthy to be integrated in trunk (or patches_321), if this is the case please refer to Adempiere forums in sourceforge to discuss the specific case.

Extensions and new classes

If you need to create new classes or extensions, please create them in the extend directory of the custom project, i.e. extend/src/org/compiere/process/MyInvoiceGenerate.java

Generation of patches.jar and customization.jar

Following the previous guidelines for project management you can generate the customization.jar file with the classes on bin subdirectory (or the selected build subdirectory in eclipse) on your custom project.

You can also generate the patches.jar (or download it from file releases on adempiere sourceforge) with the classes on bin subdirectory (or the selected build subdirectory in eclipse) on patches_321 project.

Following this approach you won't have dependencies problems with RUN_build - as you don't run RUN_build when releasing customization.jar and patches.jar - but you still need to run RUN_setup specially if you're using webstart clients, or adding packages.

IMPORTANT NOTE: The precedence on Adempiere is:

customization.jar
patches.jar (official patches_321)
Adempiere.jar (official)

With this precedence you must take account that you can have problems if your project has a customized class that is released in the patches project - you must review and apply the changes to your customized class.

Also note that the content of patches.jar and customization.jar is inserted into Adempiere.jar. Therefore, if playing around with different versions on your own patches.jar, be aware that classes you altered with the patch are not automatically changed back to normal after you installed a new patch without the changed class files.

Running Adempiere from within Eclipse

Connecting to multiple adempiere instances:
VM Arguments

-DPropertyFile=C:\Users\Carlos\AdempiereTrunk.properties

You can also use arguments to extend the memory assigned for Adempiere, i.e.:

-Xms32m -Xmx512m

Debugging Adempiere

Debugging Server

(This description uses Adempiere 3.4.2)
To debug the server you have two possibillities:
a) Shared Memory Debugging - means debugging "on site" i.e. you'll have to work at the server
b) Remote Socket Debugging - this option will be described here because very often you'll have a production system and a second one for R&D or when working at a Windows system.

Attention: DO NOT USE DEBUGGING ON A PRODUCTION SYSTEM - unless you know exactly what you are doing! Debugging will stop all server processes of the ADempiere service until you have handled it. Recommended is to use either a testing system or to stop working at the production system.

Settings at the Server

Central point is the JBOSS service with it's settings at the file [Adempiere Home]/jboss/bin/run.cfg and it's last two option lines:

# Sample JPDA settings for remote socket debuging
#JAVA_OPTS="$JAVA_OPTS -Xdebug -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=y"

# Sample JPDA settings for shared memory debugging
#JAVA_OPTS="$JAVA_OPTS -Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_shmem,server=y,suspend=n,address=jboss"

With uncommenting one of these lines you'll enable the debugging. The lower (or last) line here is the option for shared memory debugging which you can use for debugging at the server itself. The upper line have to be uncommented for external debugging means via network connection. As you can see the transport type is set to socket and what is named "address" is the port to be used on this machine.
Be aware that if your server has a firewall installed (and it should!!!) you'll have to open this particular port for using it!!
But you can use any other port too - as long as it's not beeing used by another service or program.

After changing one of these lines you'll have to restart the adempiere process. For debugging it's recommended to use [Adempiere Home]/utils/RUN_Server2.sh (or .BAT) in "normal" mode (without sending it to backgroud by " &") so you have better control of the output. After starting the service it will stop immediately with the line "Listening for transport …", which means that it's waiting for a debugging session to connect.
Now it's time for the remote part.

Settings at ECLIPSE (remote part)

First of all you'll have to open the source code that you like to have debugged and set your break points there. After that you'll be raedy for starting the debugging session. Go to "Run" -> "Debug Configurations..." - where you can find the configuration entry "Remote Java Application". Mark it and click onto "New lauch configuration" and give it a name. Normally the "Connect"-Tab used standard values like the actually opened project. Change the values as requiered, the "Connection Type" is "Standard" which means the socket connection to the debugging service. Host and port have to be set to IP address or qualified (resolvable) name of the machine to be debugged and the port number is the one you have set above.
Start debugging with the button "Debug".
You will see that you have two buttons active: "Suspend" and "Disconnect" at the debugging perspective.

Debugging session

The first thing you can examine is that the stopped session at the server now start and go ahead to normal operation, last entry is the startup time. At this point you can connect to Adempiere with a normal client - or to make it difficult using another debugging session with a client from another desktop session or computer. You can go ahead with normal operations or testing your applications up to the point where your break points become effective. A typical example for server operation is the posting of a delivery note or an invoice.
When the debugger stops it will show contents of source code with the maker set to the corresponding line. Now you can examine the value of variables and resume operations step by step (F5), line by line (F6) or go ahead to next break point or resume operations (F8).

Troubleshooting

Extending ADempiere

One good thing about Open Source ERP is that you can do things such as Extending ADempiere.

Workflows

A repeatable pattern of activity enabled by a systematic organization of resources, defined roles and mass, energy and information flows, into a work process that can be documented and learned.

BPM – Business Process Management - BPM covers activities performed by organizations to manage and, if necessary, to improve their business processes. BPM systems monitor the execution of the business processes so that managers can analyze and change processes in response to data.

Adempiere can be configured as a BPM Solution.with the matter of

In the Static (Definition) part:

Workflow: Definition of a flow of tasks – nodes and transitions
Node: Piece of work
Transition: Rules to make the transitions between nodes

The Dynamic (Execution) part:

Process: An active workflow
Activity: An active node (a process can have multiple activities in parallel)

Adempiere keeps a complete audit of every activity

States of a Workflow Server:

Not Started
- Running
  - Completed
- Suspended
  - Aborted
  - Terminated

Responsibles

Responsibles are defined on workflow level, and can be overwritten in node level. A reminder e‑mail is sent to the responsible after expected Duration.

Human: a user – when no user defined then the invoker (user who started) is the responsible
Organization: the supervisor of the document organization
Role: Any user of the assigned role

Your “Workflow Activities” tab can be considered as your to-do list (as well as the window with the same name) – in this tab you can Approve, Reject, View, Zoom to the record, Forward.

Workflow Monitoring

You can monitor all processes, activities and history from the window Workflow Process. There you can abort or assign a different user or responsible to the activity.

Creating a Workflow

Types of Actions

Apps Process – launch a predefined process
Apps Report – Issue a report, send a note with attachment to the User
Document Action – execute the defined document action
Email – send and e-mail to the defined recipient
Set Variable – set value of a column on the table that triggered the workflow
User Choice – get authorization from the approval user for the IsApproved column
Wait (Sleep) – wait the defined period of time

Transitions

When empty is unconditional
Approval (predefined)
Conditional
- AND/OR
- @Variable@/Constant Operator @Variable@/Constant

Transitions are evaluated according to sequence when more than one – evaluation left to right – no precedence
When more than one valid outgoing transition:
- XOR split = first transition only
- AND split = parallel activities
When more than one incoming transitions
- XOR join = first arrival continues workflow
- AND join = wait for completion of all activities to continue workflow

Escalations and Alerts

In the workflow you define the duration unit.
For every node you can define a duration limit. When the duration limit is reached an e-mail reminder is sent to the responsible.
In Workflow Processor you can define Inactivity alert and Reminder days, as well as Alert over Priority.

Priority

Relative number to prioritize the activities.
Activities are sorted by priority in tab.
You can configure rules to increase the priority in a time basis, i.e. Every day waiting increase priority in 5

General workflow

Simple workflow for guiding a series of tasks (one single line of execution, no conditions in transitions)
Attached directly on the menu – this is an online process

Document Process Workflow

Every document has a defined process – the workflow is started with the Process button:
These workflows have a defined start context (the document) and a responsible.

Start (Draft)
- Auto
- Prepare (In Progress)
  - Complete (Completed)

If you want to customize a workflow for a document:

for all clients
- add customized node/transitions and/or inactivate standard transitions
for a client or organization
- make changes on System workflow with entity type <> Dictionary/Adempiere
- execute process “Workflow to Client”