Apache OFBiz Development: The Beginner's Tutorial

When the check-out process is completed, we will see our OFBiz SVN workspace.

Depending on your Windows Explorer settings, you may or may not see hidden folders and files. You may see grayed out (hidden).svn folder which contains the SVN control files, something we should not have to bother with.

As we proceed and begin to change files, you may see the green ticks change to:

This means the folder (or the contents of the folder rather) has changed locally since the last update (or initial checkout). For now we do not need to worry too much about the workings of SVN. Since we will not be committing the changes back into this SVN server, we can ignore these icons.

On the JDK 5.0 download page, we should see at the top of the download items list the version for Windows Platform. We want the Windows Offline Installation, Multi-language download (at 51.42 megabytes).

The technical name for JDK 5.0 is really JDK 1.5, as can be seen from the filename jdk-1_5_0_13-windows-i586-p.exe. JDK 1.5 came in after JDK 1.4. JDK 1.5 was named JDK 5.0, possibly for marketing purposes. More details about the change of naming convention are at http://java.sun.com/j2se/1.5.0/docs/relnotes/version-5.0.html.

The version we're working with is for the operating system MS Windows 32-bit. If you're using a 64-bit operating system, you can try the version under Windows x64 Platform. The filename jdk-1_5_0_13-windows-amd64.exe suggests it may only be for an AMD 64-bit computer, but that binary should also be compatible with Intel 64-bit computers.

In case you encounter any problems with the download of the JDK 5.0, see the Sun Download and Installation Notes at http://java.sun.com/j2se/1.5.0/install.html.

Double-click on jdk-1_5_0_13-windows-i586-p.exe to start the installer. In the installation setup screen, change the Install to value to C:\Java\jdk1.5.0_13\. By default, the Java Installer may suggest to install to C:\Program Files. Installing to the default location has been seen to cause errors, particularly in the RMI (Remote Method Invocation) code on startup. This is due to the white space between Program and Files. Leave the feature Development Tools selected, and leave all other features unselected. For our purposes here, we only need the JDK and the private JRE 5.0. Proceed to complete the installation process.

Once the installation of the JDK is complete, we need to check that the environment variable JAVA_HOME is set correctly. To do this, click Start Button | Control Panel | System and select the Advanced Tab

Towards the bottom of the dialog box, you should see the Environment Variables button. There are two things to check here, first ensure that there is a variable set up called JAVA_HOME, pointing to the location C:\Java\jdk1.5.0_13 and then ensure that there is an entry under the PATH variable pointing to C:\Java\jdk1.5.0_13\bin.Entries in the PATH must be separated by a semi colon(;). If in the unlikely event these don't exist, they must be added manually, preferably as System Variables.

The first half of the log shows the compilation process itself. It should end with [echo] [build] ========== Done Building (Compile) ==========. There should be six warnings, which are due to some outdated code in the "order" component. They can be seen right above the line that says:

[jar] Building jar: ${OFBizInstallFolder}\applications\order\build\ lib\ofbiz-order.jar

These warnings can be safely ignored. Search for the keyword error to spot compilation errors. Look for unanticipated warnings. Any signs of those will mean the compilation process was not entirely successful, and has to be redone. The compilation logs will not be written to the ofbiz.log file, since the application has not yet been started.

The next half of the log shows the data loading process that loads the start-up data for OFBiz. This is the lengthy part of the ant run-install process and, depending on the speed of your computer, this part of the process could take five or even ten minutes. In comparison, the compilation process is very short, merely one to two minutes long. On successful completion of the build and seed data install, you should see a similar message to this:

BUILD SUCCESSFUL

Total time: 8 minutes 33 seconds

There are two kinds of anomalies to watch out for whose keywords are WARN and ERROR. The absence of ERROR should mean a successful data-loading process. Unfortunately, as the log message format is right now, there is no easy way to spot the truly problematic WARN logs.

Readers with some ability with Linux and the grep utility may find it useful to filter out lines containing the regular expression WARN ] .*has no table in the database. Even once these messages have been removed, we may still see other WARN logs that are problematic but not fatal show-stoppers. The stock OFBiz is still a "work-in-progress", but is not difficult to enhance quickly. As we become more competent with OFBiz, we may be able to help enhance OFBiz over time and improve the error-reporting format for the data-loading process.

Because the initial data-loading process can take so long, we should try to avoid doing it more than once. Some folks may have faster computers that can do it all in a couple of minutes, but even these folks need to consider the typical cycle of activity when dealing with software development:

The cycle goes on until we have confirmed that the new change we made satisfies our requirements and has been tested enough for us to be reasonably sure it is bug-free.

It's like performing a science experiment or trying to perfect a food recipe. After every attempt or experiment, the cooking or science apparatus need to be washed and "reset" to a clean state so that the results of subsequent attempts or experiments will not be tainted by prior ones.

In software testing, every test will change the data in some way, unless the test involves mere data retrieval. Three of the four database activities CRUD (create, retrieve, update, delete) will change the data. Even for mere retrieval tests, the software may need to write "retrieval logs", which will translate into "create-related" tests.

As can be seen, it can take five to ten minutes to wash the cooking apparatus and start over (data-loading from scratch takes that long). Perhaps buying an automatic dish-washer will cut that "reset" time down to two minutes. Now imagine if we could "reset" in just seconds.

It must be noted that any changes to the seed data itself will require a new data-loading process from scratch.

The Derby data files are in ${OFBizInstallFolder}\runtime\data\derby, contained in a folder named ofbiz.

Go to ${OFBizInstallFolder-}\runtime\data\derby and zip up the Derby data files into a single archive which you can call ofbiz_4_0_r589272.zip. Keep the archive safe somewhere. Removing the Derby data files in ${OFBizInstallFolder}\runtime\data\derby and replacing them with those in the archive will quickly "reset" our OFBiz data state.

For now, we just back up the Derby data files and move on.

Now, we start the engines! Navigate to the ${OFBizInstallFolder} in Windows Explorer and double-click the file startofbiz.bat. An un-editable command prompt window will appear. And OFBiz will startup.

As we will be frequently starting the OFBiz application, it is a good idea to make the start process quick to access. The Windows Task Bar is an ideal place to click from, as no matter what you are working on, you can start OFBiz. This can be done by right clicking on the startofbiz.bat file, creating a shortcut and then dragging and dropping the shortcut to the unlocked taskbar.

The only reliable way to confirm that OFBiz has finished its start-up process is to look at the file ${OFBizInstallFolder}\runtime\logs\console.log and check for the following lines.

Connector AJP/1.3 @ 8009 - not-secure [org.apache.jk.server.JkCoyoteHandler] started. Connector HTTP/1.1 @ 8080 - not-secure [org.apache.coyote.http11.Http11Protocol] started. Connector TLS @ 8443 - secure [org.apache.coyote.http11.Http11Protocol] started. Started Apache Tomcat/5.5.20

To make sure that OFBiz was started without any problems, search the console.log for keywords Exception and Error. The absence of those should mean that OFBiz started without any problems.

It may, at times, be convenient to see the logs in real time, rather than locating the logs to see what happened after the event. This can be done by removing the> runtime\logs\console.log part of the line in the startofbiz.bat file. The logs will no longer appear in console.log and will instead scroll inside the command prompt. The logs will still be recorded in the ofbiz.log file.

OFBiz listens on a number of ports. Think of "ports" as a house or door number. Server programs receive incoming requests from "client" components (each one operated by some end-user). There can be many programs running on one computer, with each program receiving incoming requests from any number of "client" components. Therefore, each incoming request will need to specify the port it is "knocking on", so that the server computer will know where to direct the request.

One possible problem during start-up is that any one of the ports OFBiz listens on are already occupied by another program. In this case, ${OFBizInstallFolder}\runtime\logs\console.log may contain the following lines:

[ Http11BaseProtocol.java:140:ERROR] Error initializing endpoint java.net.BindException: Address already in use: JVM_Bind:8080

which indicates port 8080 is already in use. Full instructions on changing the ports to which OFBiz listens can be found in the Apache OFBiz Production Setup Guide at http://docs.ofbiz.org/display/OFBTECH/Apache+OFBiz+Technical+Production+Setup+Guide.

Some commonly used programs including Skype, MSN Messenger, and Apple iTunes often use ports 80 and 1099 which will cause problems with start-up. If problems are experienced, these programs should be stopped.

Buy 4 Round Gizmo (fourth item down the Featured Products list, product ID GZ-2644) by entering 4 into the text field beside the item and clicking the Add to Cart button beside it. We'll see the cart (top-right of screen) now contains four items.

Click on Checkout in the Cart Summary screenlet (a screenlet is simply a sub screen, a part of the main screen). Because we're currently not logged in, OFBiz brings us to the "Login" screen. If this is the first time that you have accessed this login screen, you may notice that the URL jumps from being http://localhost:8080 to https://localhost:8443 and a warning will appear asking you if you wish to accept the certificate, in spite of a domain name mismatch. Depending on your browser, click Yes or OK to accept the temporary SSL certificate. This acceptance only applies for the "localhost" address and is perfectly safe.

For now, we do a Checkout Without Login. Click the Quick Checkout button.

The Quick Checkout button brings us to the "Shopper's Personal Info" page. In the Name Phone and Email section, enter any value for First name, Last name, Home phone, and Email address, fields that are mandatory.

In the Shipping Address section, simply fill in some values for the mandatory fields (marked by *).

Check the checkbox labeled Billing address is the same as the shipping address.

Click the Continue button at the bottom-center of the screen to confirm the shopper's (that's us!) personal info and to continue to the next step.

This brings us to the "Final Checkout Review" screen. In the Payment Information section, select Offline Payment: Check/Money Order.

In the Shipping Information section, select any shipping method desired (try the first one so we're playing with the same options).

Finally, take one last look at our order before we submit the order.

Submit the order by clicking Submit Order.

Our order will be processed and created. We are brought to the Order Confirmation screen next, which tells us that our order was successfully created.

We can take a look at the items we have successfully ordered further down the screen.

Click on the Receive Payment button in the Payment Information screenlet.

There will be many options for receiving various types of payments, such as through credit cards or paypal or gift cards (vouchers) or cash/check. Let's choose to receive cash. Enter 65.30 ($65.30) in the cash Amount field, and any random string (say cash123456) in the Reference field. Then click the Save button to confirm the receipt. You may notice that the status of the order has now moved from Created to Approved.

An Offline Payment in OFBiz is simply a convenient, manual process for receiving payments, especially for payment methods that have no automated processing implemented yet. Credit cards will usually have automated payment gateways that OFBiz can talk to for automated payment processing without human intervention. Use "Offline Payment" when encountering say an unknown credit card for which there is no automated payment processing.

Note how the Quick Ship Entire Order option now appears in the Shipment Information screenlet. Before we ship the ordered item to fulfill the order, we need to be paid.

Since we have received payment in full, it is now time to ship the order. Click on the button that says Quick Ship Entire Order.

There are actually a series of actions to be performed in order to ship and fulfill the order. This convenient quick ship function performs those actions with some default values. The order should now be fulfilled.

OFBiz components and webapps are inter-linked, forming an integrated system that qualifies as an ERP application. Let's take a peek into the webapp "accounting" to see some integration and automation in action. In the Payment Information screenlet, in the row Invoices, click on the invoice number to view the automatically generated invoice.

Note how the invoice has a zero Open amount, and has Applied Payments of $65.30. The payment that we received earlier has been automatically applied to this invoice.