Apache OFBiz®

Welcome to Apache OFBiz®! A powerful top level Apache software project. OFBiz is an Enterprise Resource Planning (ERP) System written in Java and houses a large set of libraries, entities, services and features to run all aspects of your business.

For more details about OFBiz please visit the OFBiz Documentation page:

OFBiz documentation

OFBiz License

System requirements

The only requirement to run OFBiz is to have the Java Development Kit (JDK) version 8 installed on your system (not just the JRE, but the full JDK) which you can download from the below link.

JDK download

Note: if you are using Eclipse, make sure of running the appropriate Eclipse command gradlew eclipse before creating the project in Eclipse. This command will prepare OFBiz for Eclipse with the correct classpath and settings by creating the.classpath and .project files.

Quick start

To quickly install and fire-up OFBiz, please follow the below instructions from the command line at the OFBiz top level directory (folder)

Prepare OFBiz:

Note: Depending on your Internet connection speed it might take a long time for this step to complete if you are using OFBiz for the first time as it needs to download all dependencies. So please be patient!

MS Windows: gradlew cleanAll loadDefault

Unix-like OS: ./gradlew cleanAll loadDefault

Start OFBiz:

MS Windows: gradlew ofbiz

Unix-like OS: ./gradlew ofbiz

Visit OFBiz through your browser:

Order Back Office

Accounting Back Office

Administrator interface

You can log in with the user admin and password ofbiz.

Note: the default configuration uses an embedded Java database (Apache Derby) and embedded application server components such as Apache Tomcat®, Apache Geronimo (transaction manager), etc.

---

Build system syntax

All build tasks are executed using the Gradle build system which is embedded in OFBiz. To execute build tasks go to OFBiz top-level directory (folder) and execute tasks from there.

Operating System Syntax

The syntax for tasks differ slightly between windows and Unix-like systems

• Windows: gradlew <tasks-in-here>

• Unix-like: ./gradlew <tasks-in-here>

For the rest of this document, we will use the windows syntax, if you are on a Unix-like system, you need to add the ./ to gradlew

Types of tasks in Gradle

There are two types of tasks designed for OFBiz in Gradle:

• Standard tasks: To execute general standard Gradle tasks

• OFBiz server tasks: To execute OFBiz startup commands. These tasks start with one of the following words:

  • ofbiz : standard server commands
  • ofbizDebug : server commands running in remote debug mode
  • ofbizBackground ; server commands running in a background forked process

Tips:

• OFBiz server commands require "quoting" the commands. For example: gradlew "ofbiz --help"

• Shortcuts to task names can be used by writing the first letter of every word in a task name. However, you cannot use the shortcut form for OFBiz server tasks. Example: gradlew loadAdminUserLogin -PuserLoginId=myadmin = gradlew lAUL -PuserLoginId=myadmin

Example standard tasks

gradlew build

gradlew cleanAll loadDefault testIntegration

Example OFBiz server tasks

gradlew "ofbiz --help"

gradlew "ofbizDebug --test"

gradlew "ofbizBackground --start --portoffset 10000"

gradlew "ofbiz --shutdown --portoffset 10000"

gradlew ofbiz (default is --start)

Example mixed tasks (standard and OFBiz server)

gradlew cleanAll loadDefault "ofbiz --start"

---

Quick reference

You can use the below common list of tasks as a quick reference for controlling the system. This document uses the windows task syntax, if you are on a Unix-like system, you need to add the ./ to gradlew i.e. ./gradlew

---

Help tasks

List OFBiz server commands

List all available commands to control the OFBiz server

gradlew "ofbiz --help"

List build tasks

List all available tasks from the build system

gradlew tasks

List build projects

List all available projects in the build system

gradlew projects

Gradle build system help

Show usage and options for the Gradle build system

gradlew --help

---

Server command tasks

Start OFBiz

gradlew "ofbiz --start"

start is the default server task so this also works:

gradlew ofbiz

Shutdown OFBiz

gradlew "ofbiz --shutdown"

Get OFBiz status

gradlew "ofbiz --status"

Force OFBiz shutdown

Terminate all running OFBiz server instances by calling the appropriate operating system kill command. Use this command to force OFBiz termination if the --shutdown command does not work. Usually this is needed when in the middle of data loading or testing in OFBiz.

Warning: Be careful in using this command as force termination might lead to inconsistent state / data

gradlew terminateOfbiz

Start OFBiz in remote debug mode

Starts OFBiz in remote debug mode and waits for debugger or IDEs to connect on port 5005

gradlew "ofbizDebug --start"

OR

gradlew ofbizDebug

Start OFBiz on a different port

Start OFBiz of the network port offsetted by the range provided in the argument to --portoffset

gradlew "ofbiz --start --portoffset 10000"

Start OFBiz in the background

Start OFBiz in the background by forking it to a new process and redirecting the output to runtime/logs/console.log

gradlew "ofbizBackground --start"

OR

gradlew ofbizBackground

You can also offset the port, for example:

gradlew "ofbizBackground --start --portoffset 10000"

---

Data loading tasks

OFBiz contains the following data reader types:

• seed: OFBiz and External Seed Data - to be maintained along with source and updated whenever a system deployment is updated
• seed-initial: OFBiz and External Seed Data - to be maintained along with source like other seed data, but only loaded initially and not updated when a system is updated except manually reviewing each line
• demo: OFBiz Only Demo Data
• ext: External General Data (custom)
• ext-test: External Test Data (custom)
• ext-demo: External Demo Data (custom)

you can choose which data readers to pass in the following syntax:

gradlew "ofbiz --load-data readers=<readers-here-comma-separated>"

Example:

gradlew "ofbiz --load-data readers=seed,seed-initial,ext,ext-demo"

Load default OFBiz data

Loads default data set; meant for initial loading of generic OFBiz data. Can be applied for development, testing, demonstration, etc. purposes. Be aware that executing this task can result in your data being overwritten in your database of choice. Use with caution in production environments. The default data set is defined by datasource using the read-data attribute, followed by the name of the data set, into the datasource element of the 'entityengine.xml' file.

gradlew loadDefault

OR

gradlew "ofbiz --load-data"

Load seed data

Load ONLY the seed data (not seed-initial, demo, ext* or anything else); meant for use after an update of the code to reload the seed data as it is generally maintained along with the code and needs to be in sync for operation

gradlew "ofbiz --load-data readers=seed"

load ext data

Load seed, seed-initial and ext data; meant for manual/generic testing, development, or going into production with a derived system based on stock OFBiz where the ext data basically replaces the demo data

gradlew "ofbiz --load-data readers=seed,seed-initial,ext"

load ext test data

Load seed, seed-initial, ext and ext-test data; meant for automated testing with a derived system based on stock OFBiz

gradlew "ofbiz --load-data readers=seed,seed-initial,ext,ext-test"

load data from an entity file

Load data from an XML file holding entity data.

gradlew "ofbiz --load-data file=foo/bar/FileNameHere.xml"

create a new tenant

Create a new tenant in your environment, create the delegator, load initial data with admin-user and password (needs multitenant=Y in general.properties). The following project parameters are passed:

• tenantId: mandatory
• tenantName: optional, default is value of tenantId
• domainName: optional, default is org.apache.ofbiz
• tenantReaders: optional, default value is seed,seed-initial,demo
• dbPlatform: optional, D(Derby), M(MySQL), O(Oracle), P(PostgreSQL) (default D)
• dbIp: optional, ip address of the database
• dbUser: optional, username of the database
• dbPassword: optional, password of the database

gradlew createTenant -PtenantId=mytenant

gradlew createTenant -PtenantId=mytenant -PtenantName="My Name" -PdomainName=com.example -PtenantReaders=seed,seed-initial,ext -PdbPlatform=M -PdbIp=127.0.0.1 -PdbUser=mydbuser -PdbPassword=mydbpass

If run successfully, the system creates a new tenant having:

• delegator: default#${tenandId} (e.g. default#mytenant)
• admin user: ${tenantId}-admin (e.g. mytenant-admin)
• admin user password: ofbiz

load data for a specific tenant

Load data for one specific tenant in a multitenant environment. Note that you must set multitenant=Y in general.properties and the following project parameters are passed:

• tenantId (mandatory)
• tenantReaders (optional)
• tenantComponent (optional)

gradlew loadTenant -PtenantId=mytenant

gradlew loadTenant -PtenantId=mytenant -PtenantReaders=seed,seed-initial,demo -PtenantComponent=base

---

Testing tasks

Execute all unit tests

gradlew test

Execute all integration tests

gradlew testIntegration

OR

gradlew 'ofbiz --test'

Execute an integration test case

run a test case, in this example the componnet is "entity" and the case name is "entity-tests"

gradlew "ofbiz --test component=entity --test case=entity-tests"

Execute an integration test case in debug mode

listens on port 5005

gradlew "ofbizDebug --test component=entity --test case=entity-tests"

Execute an integration test suite

listens on port 5005

gradlew "ofbiz --test component=widget --test suitename=org.apache.ofbiz.widget.test.WidgetMacroLibraryTests"

Execute an integration test suite in debug mode

listens on port 5005

gradlew "ofbizDebug --test component=widget --test suitename=org.apache.ofbiz.widget.test.WidgetMacroLibraryTests"

---

Miscellaneous tasks

Launch a graphical user interface of Gradle

This is a very convenient feature of Gradle which allows the user to interact with Gradle through a swing GUI. You can save frequently used commands in a list of favorites for frequent reuse.

gradlew --gui

Run all tests on a clean system

gradlew cleanAll loadDefault testIntegration

Clean all generated artifacts

gradlew cleanAll

Refresh the generated artifacts

gradlew clean build

Create a custom component in hot-deploy

Create a new custom component. The following project parameters are passed:

• componentName: mandatory
• componentResourceName: optional, default is the value of componentName
• webappName: optional, default is the value of componentName
• basePermission: optional, default is the UPPERCASE value of componentName

gradlew createComponent -PcomponentName=Custom

gradlew createComponent -PcomponentName=Custom -PcomponentResourceName=Custom -PwebappName=customweb -PbasePermission=MYSECURITY

Create an admin user account

Create an admin user with login name MyUserName and default password with value "ofbiz". Upon first login OFBiz will request changing the default password

gradlew loadAdminUserLogin -PuserLoginId=MyUserName

Setup eclipse project for OFBiz

Thanks to some gradle magic, setting up OFBiz on eclipse is very easy. All you need is to execute one command and then you can import the project to eclipse. This command will generate the necessary .classpath and .project files for eclipse.

gradlew eclipse

---

Useful Tips

Gradle tab-completion on Unix-like systems:

To get tab completion (auto complete gradle commands by pressing tab) you can download the script from the below link and place it in the appropriate location for your system.

Gradle tab completion

For example, on debian based systems, you can use the following command:

sudo curl -L -s https://gist.github.com/nolanlawson/8694399/raw/gradle-tab-completion.bash -o /etc/bash_completion.d/gradle-tab-completion.bash