OFBiz Tutorial – Custom Components in OFBiz

Jacopo CappellatoPublished: Updated:

This is the first of a series of posts that will introduce hands-on Apache OFBiz development: each post will focus on a simple exercise that will unveil some of the powerful features of OFBiz.

In this post we will simply setup our sandbox environment: a custom component/application named “hwm” that is deployed in OFBiz and will contain our exercises.

OFBiz components

OFBiz Components

At its bare minimum, an OFBiz component is a folder, containing a special xml file, named “ofbiz-component.xml”, that describes the resources loaded and required by the component.
OFBiz itself is made up of components:

  • framework components: lower level components that provide the technical layer and tools to the application components; the features provided by these components are typically the ones provided by any other development framework (data layer, business logic layer, transaction handling, data source pools, etc…)
  • application components: they are generic ERP applications that can be used as they are or extended/customized (product, order, party, manufacturing, accounting etc…); application components have access to the services and tools provided by the framework components and to the services published by other application components
  • special purpose components: similar to the application components, the are special purpose applications like ecommerce, Google Base integration, eBay integration etc…
  • hot-deploy components: this folder is empty and it is where you can place your custom components; custom components have access to, and can extend/override, the resources published by all the other components


  • JDK 1.6 is properly installed and the JAVA_HOME environment variable is correctly set; you can download Java from java.sun.com
  • an svn client is installed in your system (needed to checkout the latest OFBiz sources); you can freely download an svn client from tigris.org

Setting up the sandbox

These are the simple steps to download and build OFBiz and your custom component:

  1. Download the OFBiz source files from the official OFBiz SVN Respository (this step can take some time and requires access to the Internet): “svn co http://svn.apache.org/repos/asf/ofbiz/trunk ofbiz”
  2. go to the newly created folder: “cd ofbiz”
  3. run the ant task to create a standard OFBiz component: “./ant create-component” (and answer the questions when prompted, see below for details)
  4. build OFBiz and load the demo data: “./ant run-install”
  5. run OFBiz: “./ant run”

In short, here are the commands you have to type in a shell:

Now OFBiz and your custom applications are up and running; just point your browser to: http://localhost:8080/hwm
Login into the custom “hwm” application with username “admin” and password “ofbiz”.

More about the “create-component” script

Even if you can of course manually create an hot-deploy component, running the ant task “create-component” is the preferred way of starting with a new hot-deploy component because it is quick and generates a component layout that follows all the OFBiz best practices, enabling you to use and extend the existing OFBiz goodies:

  • entities (the data model)
  • services (business logic)
  • widgets (user interface elements like screens, forms, menus)
  • security (authentication and authorization)
  • localization
  • tools
  • etc…

The main advantage of using this development strategy is that all your custom code will be separated from the official OFBiz code, drastically simplifying the task of keeping your custom application updated with the new OFBiz versions. You will still be able to extend/override/customize specific OFBiz entities, services, screens and of course add new ones, just writing code into your custom component.

For the most curious of you, here are some details about the meaning of the questions asked by the “create-component” script:

  • component name: this is the name of the component (and also of the folder that will contain it, created in the hot-deploy folder); following OFBiz’s naming conventions, it should be a single word all lowercased (e.g. hwm)
  • component resource name: it will be used as a prefix for resources; you can just use the component name, possibly using an upper case character for the first character in the words (e.g. Hwm)
  • webapp name: this is the name and uri of the application in which the ui for the new component will be implemented; following OFBiz’s naming conventions, it should be a single word all lowercased (e.g. hwm)
  • base permission: this is the prefix for base security permissions; following OFBiz’s naming conventions, it should be a single word all uppercased (e.g. HWM)

Based on the answers provided, the script will setup a new component in the “hot-deploy” folder, with the following layout:

The layout of the custom component "hwm"

The layout of the custom component “hwm”

You may already recognize how the information collected from the user by the script has been used to generate the component.

Exploring the component layout

Now we have everything we need to start to practice with the development based on the OFBiz framework. In the upcoming posts we will use this component to perform some exercises that will help us to better understand how OFBiz works and how to use it to build powerful erp applications.

– Jacopo

Jacopo Cappellato About Jacopo Cappellato
Jacopo Cappellato is VP of Technology at HotWax Media and has been involved with the OFBiz project since 2003. He is an OFBiz Project Committer and a member of both the OFBiz Project Management Committee and the Apache Software Foundation.

Comments 18

  1. Pingback: OFBiz Tutorial - Building A Simple Product List Screen | Apache OfBiz Blog - HotWax Media

  2. After completing the tutorial I tried a “ant build” and an “ant run-install”, but it doesn’t like the build.xml file from the create-component command.

    /opt/ofbiz-release9.04/build.xml:157: The following error occurred while executing this line:
    Target “classes” does not exist in the project “OFBiz – Hwm Component”. It is used from target “jar”.

    Now I noticed that there are no classes in hwm/build/classes, should I disable or delete the build.xml file to get around this error?

    Thanks, and thanks for the other response.

    1. Hi Patrick,

      thank you for your interest about our blog.
      I have noticed that you are running the tutorial using the OFBiz release 9.04 version; my suggestion is to use a newer version (the trunk or a nightly build that you can easily download from here ).
      BTW, today I have tested the tutorial using the release 9.04 and it worked. What JDK version are you using? I guess it is a 1.4 version and the “classes” target of the generated “hwm” component requires 1.5 or above.
      Let us know if this helps you.


  3. Pingback: OFBiz Tutorial - Enhancing the Product list screen | Apache OfBiz Blog - HotWax Media

  4. Thanks for the tutorial. It worked perfectly for me. I’m looking forward seeing what kind of applications I can create with OFBiz.

  5. Thanks for the info on the sandbox. I have been having trouble getting my sandbox to work.
    Great Tutorial. Thank You.

  6. Hotwax,

    Thanks for the tutorial. Helped me get around a few problems that I have been struggling with for the past couple of hours.


  7. hi, thanks for the tutorial, but unfortunately i can’t make it works 🙁
    i’ve got this error:

    org.ofbiz.widget.screen.ScreenRenderException: Error rendering screen [component://test/widget/CommonScreens.xml#main-decorator]: java.lang.IllegalArgumentException: Could not find resource bundle [TestUiLabels] in the locale [en_US] (Could not find resource bundle [TestUiLabels] in the locale [en_US])

    do you know what went wrong?

    any help would be appreciated 🙂

    1. Hi Arini,

      sorry for the awfully late reply to your question. You are getting that error because the renderer can’t locate the file Tes1UiLabels.xml; please check if the file is in the config folder.

      Kind regards,


  8. Hi,
    I’m not getting the following message.
    org.ofbiz.widget.screen.ScreenRenderException: Error rendering screen [component://test/widget/CommonScreens.xml#main-decorator]: java.lang.IllegalArgumentException: Could not find resource bundle [TestUiLabels] in the locale [en_US] (Could not find resource bundle [TestUiLabels] in the locale [en_US])
    Can you help me out here.


Leave a Reply

Your email address will not be published. Required fields are marked *