OFBiz USER GUIDE PDF

OFBiz 开发指南系列

Apache OFBiz Quick Start Guide

Hongs 收集整理
Contact：billhongs@gmail.com

Last updated on 2008‐10‐05

Quick Start
Apache OFBiz Project Overview
Purpose
The Purpose of this document is to give you an overview of the Open For Business Project from a
business perspective. It will review some of the principles and motivations behind the project, major
application components, and a brief explanation of the system's technical organization.
The descriptions of functionality in this document are meant to give you a high level overview of the
system. For more detailed information you can look over the Feature List and related documents.
Introduction
Open For Business (OFBiz) is a suite of enterprise applications built on a common architecture using
common data, logic and process components. The loosely coupled nature of the applications makes
these components easy to understand, extend and customize.
The tools and architecture of OFBiz make it easy to efficiently develop and maintain enterprise
applications. This makes it possible for us as the creators and maintainers of the project to quickly
release new functionality and maintain existing functionality without extensive effort. It also makes it
easy to customize and extend existing functionality when you have a specific need.
The architecture alone makes it easier for you to customize the applications to your needs, but many of
the best flexibility points in the system would be meaningless and even impossible if the system was not
distributed as open source software. OFBiz is licensed under the Apache License Version 2.0 which grants
you the right to customize, extend, modify, repackage, resell, and many other potential uses of the
system.
No restrictions are placed on these activities because we feel that they are necessary for effective use of
this type of software. Unlike other open source licenses, such as the GPL, your changes do not have to
be released as open source. There are obvious benefits to contributing certain improvements, fixes and
additions back to the core project, but some changes will involve proprietary or confidential information
that must not be released to the public. For this reason OFBiz uses the Apache License Version 2.0 which
does not require this. For more information on open source licenses see the Open Source Initiative (OSI)
web site at www.opensource.org.
Another benefit of this open source model is that we receive constant feedback from those who are using
the software. We have received countless bug fixes, improvement suggestions, and best-practice
business advice from users and potential users of OFBiz. Many of the greatest features in the project
were inspired by some comment or suggestion sent to the mailing lists associated with the project. With
dozens of organizations using the software and probably hundreds of deployed sites using one piece or
another of the project we generally get 20-30 emails each day about the project.
To make sure our functionality is timely and useful we always start by researching public standards and
common usage for any component we are working on. This helps us support and use common
vocabularies and gives us an instant breadth of options and features that can only be achieved through
standards processes and other group efforts. It also opens doors in the future for flexible communication
with other systems that are built around the same standards, both inside your organization and in
partner or other organizations.
The applications and application components that come with the system provide you with a broad and
flexible basis that can be used as-is with the best-practices based designs, or customized to your own
special needs. The applications facilitate management of everything from parties and products to
accounting, customer service and internal resource and asset management. Which brings us to the next
topic...
Major Application Components
Through collaboration in a large community and an ongoing development effort OFBiz hopes to include
features that automate every aspect of enterprise information and knowledge. Early in the development
and design of the project we were searching for a good initial data model to use as a foundation for the
system.
We researched other ERP and CRM systems and looked at various general and system specific books
before finding The Data Model Resource Book, Revised Edition, Volumes 1 and 2 by Len Silverston. After
a few weeks of translating the logical data models described in these books into flexible and normalized
physical data models we had our initial system organization. Since that time the initial data model has
gone through hundreds of revisions and refinements based on real-life use of the system and
compatibility with dozens of existing public standards. Because of the flexible system architecture it is
easy to make changes to the data model. This is necessary for the ongoing improvement of the project
and makes it easy for you to make changes that suit your specific needs.
The top level applications and application logic components are organized in almost the same structure
as the data model. Once the organization of one level of the system is understood moving to other levels
in the system takes very little effort.
The following is a brief overview of the major functional areas of the system. Many of these have
functionality that exists now and all have data elements defined that cover the needs of that part of the
system. As further functionality is implemented we continually refine the data model, but all of the major
data element definitions are in place. So, just remember that much, but not all, of the functionality
described here is implemented at this point.
Common Data
The Common Data in the system includes entities such as Geographic Boundaries, Units of Measure,
Status Codes, Enumerations, and so forth. Most of this data is seed data that is imported when the
system is installed and generally needs very few changes over time. Geographic boundary and other
applicable seed data is based on ISO and other standards.
Content
The Content entities are used to track data resources and structure them into general content and
knowledge. They include many concepts such as: a separation of information and organization allowing
a data resource to be used in many content structures; flexible organization of content including
free-from association in graphs or more constrained organization in trees, lists, named maps, templates,
etc; the specification of meta-data for content and data resources that can be used to implicitly organize
and explicitly describe the information. Individual pieces of content can be in various text and binary
formats described by standard MIME types and character encodings.
Once general maintenance tools for this information are in place more advanced tools such as keyword
based, meta-data based, and intelligent searching or text mining to automatically create additional
structure or meta-data can be used to enable enterprise wide document and knowledge management.
The Content entities also include information about Web-based content such as pages and interaction
with content including visits to a site (or application) and information about every request sent to the site.
This is useful for tracking what users are doing with an application for security, marketing, usability and
other reasons.
Security
The Security entities are used to control access to various parts of the system and include user login
accounts, login audit data, permission data, and so forth. Additional more restrictive security is
accomplished through the Party entities and the association of Parties to various other data in specific
Roles. For instance one user might have a Permission to view and modify all Product data where another
user only has permission to view and modify the Product data if the user is associated as a Merchandiser
with a category that the product is in.
Party
A Party can be either a Person, or a group of Parties. A Party Group could be a company, an organization
within the company, a supplier, a customer, and so forth. Information that describes Parties or is directly
related to Parties is contained in these entities.
One type of related data is Contact Mechanisms such as postal addresses, phone numbers, email
addresses, internet URLs. Another is Roles that the Party acts in such as Customer, Supplier, Employee,
Manager, Merchandiser, etc. Generally a single party will interact with different parts of the system in
many different roles.
Another type of data that fits into the Party category is information about communication and
agreements between Parties. This gets into the area of relationship management and also includes
information about issues or trouble tickets that a Party may have. These entities are used along with the
Work Effort entities to plan and track the research and resolution of such issues.
Product
The Product entities contain information about products that are for sale or for use within a company.
Products can be goods or services and there are various types of goods including raw materials,
subassemblies and finished goods. Product information includes descriptive information about the
products but is not used for describing actual instances (where applicable) or physical goods, that is
where Inventory Items come into play. An Inventory Item contains information about where a particular
good is located, the status of the item, and a serial number for serialized items or quantity on hand and
available to promise amounts for non-serialized inventory.
Products can be organized into Product Categories. A single product can be a member of multiple
categories and even categories themselves can be children of multiple categories and can have multiple
child categories. Products can also be associated with one another to designate concepts such as
variants, cross-sells, up-sells, marketing packages, etc.
Categories can be associated with different Catalogs. A Product Catalog is essentially a starting point for
all information about a particular set of products to be sold. Promotions and inventory management
options are associated with each catalog so that different sales channels can behave differently even
with the same set of underlying products.
To flexibly model different types of features that products often have there are entities for defining types
of features and actual features that can be applied to products. For instance, you might say that this shirt
is a size large and is a blue colored shirt. Size and color are types of features and large and blue are
actual features applied to the specific shirt product.
Multiple prices can be associated with a single product, as can multiple costs. Different prices can be
specified for different currencies, different sets of facilities (or stores), and for different date ranges.
This is a good place to introduce the wide-spread use of effective dating in OFBiz. There are two fields
commonly used to express effective dates: fromDate and thruDate. In the product price example the
fromDate and thruDate are used to denote that a price goes into effect on a certain date and at a certain
time and expires at a certain date and time. This can be used to keep a history of price changes, and to
effectively manage temporary promotional prices.
In addition to explicitly specifying prices there are also entities and logic that uses the entities to have
rules about prices. For instance you could create a rule that is in effect for a certain time period that puts
all of the products in a certain category on sale. Or, you could give special prices to specific customers or
groups of customers with a simple rule.
Order
The Order entities are used to manage information about sales and purchase orders and information
leading up to an order. For example a request for a specific product or feature may be submitted by a
customer and that would be tracked by the request entities in the Order package.
The request can be tracked and turned into a requirement which can be used to create a Work Effort (a
task, for instance; see the Work Effort section below) to be created that will satisfy the requirement and
fulfill the request. Once a requirement is made a quote can be produced which if accepted by the
customer can be used to create an order. Once an order is fulfilled an invoice can be created from the
order. Invoices are part of the Accounting entity package described below.
Orders consist of an Order Header and any number of Order Line Items and Adjustments that describe
the detail of the Order. There are various pieces of information related to an Order that can be associated
with either the header or an individual or multiple line items of an order. Examples include the shipping
destination and shipping preferences of an order which may be the same for all line items, or may be
different for each one.
Adjustments are used to contain information about things that change the price of an order that are not
actual goods or services sold or purchased. Examples include taxes, shipping, discounts, surcharges,
and so forth. An adjustment can be either a flat amount, a flat amount per quantity, or a percentage of
the subtotal of the entire order or the line item it is associated with. Tax and shipping are handled as
special cases and each adjustment can specify whether or not it should be included in the sub-total for
tax and/or the sub-total for shipping.
Payment preferences can be tracked as an order is created to automate payment once an invoice is
created. This is especially useful for payment by credit card or other electronic means. If no payment
preferences are specified then a standard invoicing and billing process can be used.
Facility
A Facility is a building or other physical location. Examples include warehouses, stores, office buildings,
individual rooms in a larger facility, loading docks, et cetera. Generally a facility will have Contact
Mechanisms associated with it such as a postal address or a phone number.
Facilities can be grouped into Facility Groups which in turn can be contained in other Facility Groups.
Examples of groups include store chains, districts, regions, and special groups used for marketing or the
pricing of products.
Inventory Items can be associated with a facility and even a specific location within a facility. Facility
Locations can be tracked and managed independently of the Inventory Items they contain for easy
management of warehouse spaces and easy location of specific Inventory Items.
Parties can be associated with Facilities to represent where a person works, which organization controls
or operates the facility, who manages the facility, et cetera.
Shipment
The Shipment entities are used to track incoming and outgoing shipments and to issue items from
inventory or receive items into inventory.
A Shipment consists of multiple Shipment Items each of which, like an Order Item, represents a certain
quantity of a specific Product. When Shipments are received they can be reconciled with a purchase
order and that information is tracked in the Shipment Receipt entity.
When an Inventory Item is issued for an outgoing shipment it is associated with a Pick List that can be
prepared from multiple Shipments to more efficiently route the picking path in the warehouse or other
facility.
Shipment Packages can be created which represent a single box or shipping unit. A single box can
contain multiple Shipment Items, even items from different Shipments assuming that they are going to
the same destination.
The Shipment Route entities are used to split up a Shipment's journey into multiple route segments. One
route segment for a Shipment could be a commercial carrier while another could be a private carrier or
a company owned truck.
Accounting
The Accounting entities are organized according to age old and generally accepted principles such as
double-entry accounting, a General Ledger with hierarchical accounts, journals and posting of
transactions and corresponding entries. The structure is primarily based on the OMG GL standard and
the work that was done on an AR/AP extension of the OMG GL standard. This correlates well with other
standards such as ebXML and OAGIS.
The Accounting entities are structured such that accounts for multiple organizations can be managed.
The multiple organizations could be multiple companies, or departments or other organizations within a
company. Each Organization can have various GL Accounts associated with it so that it can operate with
its own subset of the Master Chart of Accounts. Each Organization can also have its own set of Journals
for flexibility, even though the use of Journals should be as minimal as possible in favor of allowing the
system to automatically create and post transactions based on business events triggered by standard
procedures and documents such as purchase and sales orders, invoices, inventory transfers, payments,
receipts, and so forth.
There are also entities in place for budgeting and the reconciliation of budgets against actual GL Account
balances for a specific fiscal period. Oh yeah, there are also entities used to track custom Fiscal Periods
and other entities to keep summary results for accounts in specific periods.
Entities to track Fixed Assets are also part of the Accounting entity package. This includes depreciation
information in addition to maintenance, scheduling of Fixed Assets (along with the Work Effort entities),
and so forth.
Marketing
The Marketing entities are used to track information about Marketing Campaigns and related information
such as Contact Lists (mailing, email, or calling lists) and Tracking Codes. Tracking Codes are primarily
used in automated systems to keep track of where a customer came from and can be used for
commission purposes in addition to analyzing the effectiveness of specific Marketing Campaigns
including advertisements, partnerships or affiliations, and so forth.
Work Effort
A Work Effort can be one of many things including a task, project, project phase, to-do item, calendar
item, or even a Workflow(deprecated) or a Workflow(deprecated) Activity.
Workflow(deprecated)s are a special case and are managed by the OFBiz Workflow(deprecated) Engine.
A Workflow(deprecated) is essentially a semi-automated process that involves both automatic activities
performed by the computer and manual activities performed by a human or some other external system
controlled by a human. The Workflow(deprecated) Engine processes Workflow(deprecated)s defined in
special entities modeled after the Workflow(deprecated) Management Coalition (WfMC.org)
specifications. XPDL files can be imported into these entities and then the Workflow(deprecated)s
defined there can be invoked through various means. The Workflow(deprecated) Engine keeps track of
everything that has been done and that needs to be done for the processes that it runs.
There are also entities in the Work Effort entity package for keeping track of timesheets and the pay rate
of specific Parties performing Work Efforts. In addition various other resources can be tracked such as
Fixed Assets, Facilities, et cetera.
When Work Efforts are used for manufacturing or other modification of Products the Products and
Inventory Items consumed and produced by the specific Work Effort can be tracked.
Human Resources
The Human Resources entities are used to keep track of positions, responsibilities, skills, employment,
termination, benefits, training, pay grades and payroll preferences, performance reviews, resumes and
applications, and other Human Resources related information.
Architecture and System Organization
Architecture is really just a fancy word for the organization and composition of application components.
There are many different "tools" available as part of Java, J2EE and the OFBiz Core Framework that can
be used together to efficiently and effectively organize data and business logic, to provide interfaces to
other systems, and to create user interfaces for humans to interact with the system.
Entities and Services
The most basic components in OFBiz are Entities and Services. An Entity is a relational data construct
that contains any number of Fields and can be related to other entities. Basic entities correspond to
actual database structures. There is also a type of entity called a "view-entity" that can be used to create
a virtual entity from other entities to combine sets of fields by joining other entities together. These
constructs can be used to summarize and group data and in general prepare it for viewing or use in a
program.
In many architectures the data or persistence layer alone consists of hundreds of thousands or millions
of lines of code that must be maintained as the system is developed and customized. With the Entity
Engine this is all distilled into only thousands of lines of XML data definitions that drive an easy to
dynamic API. Even less-experienced programmers can become productive with this tool in a few days
and never have to learn any SQL. It takes care of that for you!
You have probably heard some of the "Web Services" buzz that has spread to every corner of the
software industry. The OFBiz system not only uses the service pattern to communicate with other
systems, it also uses the service pattern inside the system to provide a clean and easy to use facility for
creating and running business logic components.
A Service is a simple process that performs a specific operation. A service definition is used to define the
input and output parameters that the service consumes and produces. Data passed to the service can be
automatically validated before the actual logic is called using this definition. After a service is run the
results can be validated in the same way.
Other services can be run automatically at different points of the running of a service by using
Event-Condition-Action (ECA) rules to denote what other services should be called and under what
circumstances. This allows logic to be extended without modifying the original logic and allows the
system to be organized cleanly such that each service performs one simple, specific task.
Services can be implemented in a number of different ways to make it easier for engineers to match the
tools available to the task at hand. It also makes it easy to keep track of the logic components in the
system which may exists in hundred of different files and even on different computers used inside the
company or computers of a partnering company.
Workflow and Rules(deprecated)
The Workflow(deprecated) Engine, which is described briefly in the Work Effort section above, can be
used to automate business processes consisting of both manual (humanly performed) and automatic
(computer performed) activities. Workflow(deprecated)s can be called as services and automated
activities within a Workflow(deprecated) can call services allowing unlimited flexibility in combining
these small logical components.
The purpose of Workflow(deprecated) tools is to automate and track complex business processes. They
can help to insure that your policies are followed and that important tasks are not lost in the chaos and
confusion that even reasonably sized organizations often operate in. A good example of this is the Order
Manager in OFBiz which is Workflow(deprecated) based. When an order is placed a Workflow(deprecated)
is started and tracked through approval and fulfillment of the order. With this tool it is easy to see what
has happened to a specific order and what still needs to be done with the order.
There are many other examples of processes that can benefit by this sort of management. For example:
content creation and publishing, customer issue, complaint and service management, sales cycle
management, and any other business process that involves the coordination of different people in
different roles.
The Rule Engine in OFBiz is essentially an alternative programming language that is based on concepts
completely different from procedural programming languages like Java, Basic, C, Cobol, and so forth.
Facts and rules are declared and then used in one of two ways: 1) asking if a specific assertion is true and
showing all possible proofs of the assertion, and 2) presenting all information available and asking the
Rule Engine to produce all other information possible given the facts and rules it knows about.
Rule engines can be used for many different applications. They are most useful for decision support and
helping humans analyze situations that are too complex to do on paper or in one's head or by any means
because of the amount of time that would be involved. Using the rules as constraints and finding all valid
solutions to a problems such as airport gate assignments or truck delivery and pickup routing can save
countless hours and allow for consistent application of rules that a human might occasionally miss or
forget no matter how experienced that person is.
Web Framework and XML MiniLanguages
There are many useful tools in the OFBiz Core Framework that address points of difficulty in web,
client-server and peer-to-peer based enterprise applications. A tool exists for simplifying the use of flat
data files making it easier to integrate with legacy systems. Various tools exist for organizing and
structuring web-based content and applications with a flexible separation of logic and presentation.
These tools along with the standard J2EE and other Java tools make it easy for the system to
communicate with human users and other systems.
To make it easier to use these Core Framework tools another component called an XML Mini-Language
has been created that allows an engineer or other user to create an XML file with simple, well-defined
instructions that the system can understand and execute. Expressing logic in a Mini-Lang
"simple-method" often requires only one third as much code as an equivalent Java method and is much
easier to read and modify for semi-technical users. Processing form input, composing services into larger
services, and interacting with data in the database are common things that can be done easily with this
tool.
Conclusion
The Open For Business Project is a collaborative effort involving a large group of users and developers
and is moderated by a small central team. The applications and framework components are being used
in a wide variety of businesses and applications and are customized heavily in many circumstances to
meet the needs of the organizations using the software.
This is only possible and can only operate efficiently and effectively as an open source project. This is in
sharp contrast to the style of most commercial vendors that restrict many possible uses of and
extensions to their software through design limitations or licensing restrictions in order to extract a
greater profit from the use of the software. Much of the early commercial software was much more
flexible and open and less restrictive than many modern packages. As that trend continues more
developers and users of software start to consider a more trusting alternative.
While those who contribute to the project, including the moderators, choose not to force others who use
it to pay them, they can benefit in many other ways. Often you will find that the system is so close to
what you need that a small amount of effort on your part can change the system to be perfect for you.
If that effort is contributed back to the community others in a similar situation can help improve and
maintain it. You as the contributor you can freely upgrade your own system with other improvements in
the main project without having to worry about your changes that might conflict with his addition.
In general OFBiz is meant to provide so much value that you will be willing and happy to contribute
something back and keep the effort going. This again is in sharp contrast to the commecial approach of
forcing users to pay for every right of use or modification related to the software. The open source
approach enables information sharing and that information can be leveraged by all in the community to
improve the use of the software for their own needs.
So, for the moderators of the project, what do we get for all of the time spent designing frameworks and
applications, writing code, and answering questions? It goes back to the basic law of the harvest: you
reap what you sow. The more value something provides, the more it is worth. For us it is an opportunity
to be at the nexus of such a project and to be at least somewhat involved in helping it grow. This gives
us the chance to work with you and provide services in return for revenue that keeps the project going.
Our only hope is that you will be able to derive as much value from the project as we have.
Running opentaps/OFBiz
Prerequisites
Before you can start running and using opentaps/OFBiz, you will need to download and install Java
1.4 (1.5 or higher will work too.)
If you plan on building opentaps or OFBiz from the source code, you will also need Apache Ant
version 1.6 or better. Make sure you have version 1.6+. Some versions of Linux come with Ant
1.5 pre-installed. Those will not work.
Finally, if you wish to be able to check out the OFBiz source code, you will need Subversion.
Downloading and Building
First, get a current copy of opentaps or OFBiz. If you are looking for a relatively stable production
version, download opentaps from SourceForge.net. If you are a developer looking for the latest
version, you can use subversion to download the latest OFBiz source code or download a weekly
build.
If you have either the opentaps download or the OFBiz weekly build, you just need to unzip it. If
you downloaded the OFBiz source code, go to your new ofbiz directory to build it and install the
seed and demo data:
$ ant run-install
or, if you are using Windows and assuming that you installed ant in c:\ant:
C:\ofbiz> c:\ant\bin\ant run-install

from a Windows command line shell.
Getting It Started
Your copy of opentaps or OFBiz comes with embedded servers and databases, so running it is very
simple.
To run the opentaps or OFBiz server, which runs all the applications except Point Of Sales, go to
your new opentaps or ofbiz directory and type:
$ ./startofbiz.sh
$ tail -f logs/console.log
or from Windows:
C:\ofbiz> startofbiz.bat
Note that the log file is directly displayed in the shell window in Windows but saved to
logs/console.log in Unix/Linux systems, hence the need for the tail command.
Now open up a browser and type into the navigation bar:
http://localhost:8080/ordermgr/control/main
You will be prompted for a username and password. For the demo, use "admin" for username and
"ofbiz" for password. You should be logged in and see this screen. Now you can start exploring
opentaps/OFBiz.
To run the POS terminal instead, do the following from your ofbiz directory, in either Windows or
Unix/Linux:
$ java -jar ofbiz.jar -pos

You will first see a logo and then the POS terminal show up. Type in "1" for the username and "1"
for the password to log in as the manager.
A Tour of OFBiz
This tutorial will walk you through OFBiz and one of its applications to help you understand the
structure of OFBiz.
First, go into your OFBiz directory and take a look inside:
[sichen@localhost ofbiz_5010]$ ls -l
total 88
drwxrwxr-x 15 sichen sichen 4096 May 20 07:54 applications
drwxrwxr-x 8 sichen sichen 4096 May 20 07:59 base
-rw-rw-r-- 1 sichen sichen 10173 May 20 07:58 build.xml
drwxrwxr-x 4 sichen sichen 4096 May 20 07:59 data
drwxrwxr-x 24 sichen sichen 4096 May 20 07:58 framework
drwxrwxr-x 3 sichen sichen 4096 May 20 07:52 hot-deploy
-rwxrwxr-x 1 sichen sichen 309 May 20 07:58 ij.ofbiz
drwxrwxr-x 2 sichen sichen 4096 May 20 08:08 logs
-rw-rw-r-- 1 sichen sichen 21167 May 20 08:07 ofbiz.jar
-rw-rw-r-- 1 sichen sichen 2869 May 20 07:58 rc.ofbiz
drwxrwxr-x 6 sichen sichen 4096 May 20 07:55 specialized
-rw-rw-r-- 1 sichen sichen 265 May 20 07:58 startofbiz.bat
-rwxrw-r-- 1 sichen sichen 790 May 20 07:58 startofbiz.sh
-rwxrw-r-- 1 sichen sichen 325 May 20 07:58 stopofbiz.sh
drwxrwxr-x 12 sichen sichen 4096 May 20 07:52 website
Things to note here:
o OFBiz is built around a components-based architecture, which means each application is

inside a component. This allows outside or custom applications to be added easily.
o The applications/ directory holds the applications components, such as order manager and
ecommerce store.
o The framework/ directory holds the components for the OFBiz framework, such as the
entity engine, and service engine.
o specialized/ contains some other applications which are not part of the OFBiz core.
o hot-deploy/ is another directory where components can be dropped in and automatically
loaded.
o base/ contains code for starting up and configuring ofbiz.
o logs/ contains log files. On Unix/Linux, ofbiz runs as a background process, and all console
output is in logs/console.log
o website/ is the contents of ofbiz.org.
Now let's go inside framework/ and take a look:
[sichen@localhost ofbiz_5010]$ cd framework/

[sichen@localhost framework]$ ls -l
total 88
drwxrwxr-x 7 sichen sichen 4096 May 20 08:00 appserver
drwxrwxr-x 8 sichen sichen 4096 May 20 07:59 catalina
drwxrwxr-x 12 sichen sichen 4096 May 20 08:00 common
-rw-rw-r-- 1 sichen sichen 2988 May 20 07:58 component-load.xml
drwxrwxr-x 6 sichen sichen 4096 May 20 07:59 datafile
drwxrwxr-x 10 sichen sichen 4096 May 20 07:59 entity
drwxrwxr-x 9 sichen sichen 4096 May 20 07:59 entityext
drwxrwxr-x 12 sichen sichen 4096 May 20 07:55 example
drwxrwxr-x 6 sichen sichen 4096 May 20 08:00 guiapp
drwxrwxr-x 4 sichen sichen 4096 May 20 07:56 images
drwxrwxr-x 6 sichen sichen 4096 May 20 07:59 jetty
drwxrwxr-x 7 sichen sichen 4096 May 20 07:59 jotm
drwxrwxr-x 6 sichen sichen 4096 May 20 07:59 minerva
drwxrwxr-x 7 sichen sichen 4096 May 20 08:00 minilang
drwxrwxr-x 9 sichen sichen 4096 May 20 07:59 security
drwxrwxr-x 11 sichen sichen 4096 May 20 07:59 service
drwxrwxr-x 12 sichen sichen 4096 May 20 08:00 shark
drwxrwxr-x 10 sichen sichen 4096 May 20 08:00 tests
drwxrwxr-x 9 sichen sichen 4096 May 20 08:00 webapp
drwxrwxr-x 9 sichen sichen 4096 May 20 08:00 webtools
drwxrwxr-x 6 sichen sichen 4096 May 20 08:00 widget
drwxrwxr-x 9 sichen sichen 4096 May 20 08:00 workflow
These are the components of the OFBiz framework, which is used to develop the OFBiz applications.
component-load.xml controls which of the components in the current directory are loaded.
Now go back and take a look at the applications themselves:
[sichen@localhost framework]$ cd ..
[sichen@localhost ofbiz_5010]$ cd applications/
[sichen@localhost applications]$ ls -l
total 52
drwxrwxr-x 13 sichen sichen 4096 May 20 08:00 accounting
-rw-rw-r-- 1 sichen sichen 2425 May 20 07:54 component-load.xml
drwxrwxr-x 15 sichen sichen 4096 May 20 08:00 content
drwxrwxr-x 11 sichen sichen 4096 May 20 08:00 ecommerce
drwxrwxr-x 5 sichen sichen 4096 May 20 07:53 humanres
drwxrwxr-x 12 sichen sichen 4096 May 20 08:00 manufacturing
drwxrwxr-x 12 sichen sichen 4096 May 20 08:00 marketing
drwxrwxr-x 13 sichen sichen 4096 May 20 08:00 order
drwxrwxr-x 12 sichen sichen 4096 May 20 08:00 party
drwxrwxr-x 12 sichen sichen 4096 May 20 08:00 pos
drwxrwxr-x 12 sichen sichen 4096 May 20 08:00 product
drwxrwxr-x 10 sichen sichen 4096 May 20 08:00 securityext
drwxrwxr-x 12 sichen sichen 4096 May 20 08:00 workeffort
These are the OFBiz applications themselves. Each application is self-contained with its own data
model definitions, business logic, and presentation (web or Swing) tier, although applications may
reuse each others' business logic and thus depend on each other.
Now let's go inside an application and see what it looks like:
[sichen@localhost applications]$ cd product/

[sichen@localhost product]$ ls -l
total 52
drwxrwxr-x 4 sichen sichen 4096 May 20 08:08 build
-rw-rw-r-- 1 sichen sichen 6413 May 20 07:53 build.xml
drwxrwxr-x 3 sichen sichen 4096 May 20 07:53 config
drwxrwxr-x 3 sichen sichen 4096 May 20 07:53 data
drwxrwxr-x 3 sichen sichen 4096 May 20 07:53 entitydef
-rw-rw-r-- 1 sichen sichen 4202 May 20 07:53 ofbiz-component.xml
drwxrwxr-x 4 sichen sichen 4096 May 20 07:53 script
drwxrwxr-x 3 sichen sichen 4096 May 20 07:53 servicedef
drwxrwxr-x 4 sichen sichen 4096 May 20 07:53 src
drwxrwxr-x 5 sichen sichen 4096 May 20 07:53 webapp
drwxrwxr-x 5 sichen sichen 4096 May 20 07:53 widget
Here is what you are seeing:
o build/ is where the compiled Java code and any libraries for this application go.
o build.xml tells ant how to build this application. It is like a Makefile.
o config/ is for configuration data, such as internationalization (i18n) UI labels in various
languages.
o data/ is where the seed and demo data, in XML format, are located.
o entitydef/ is where the data model definitions of this application are.
o script/ is where scripts for business logic are. Scripts can be written in beanshell, OFBiz
minilang, Jython, etc.
o servicedef/ is where the services, which are small, granular pieces of business logic
(similar to functions or methods), are defined.
o src/ is where Java classes for implementing business logic are.
o webapp/ is where the web interface, or front end, applications are. An OFBiz application
can have more than one webapp.
o ofbiz-component.xml defines this application by specifying where its data model, business
logic, seed data, and web applications are located.
A look inside the entitydef/ and servicedef/ directories will show the XML files used to define the
data model and business logic, respectively:
[si@localhost product]$ ls -l entitydef/

total 264
-rw-rw-r-- 1 si si 3094 May 27 08:00 eecas.xml
-rw-rw-r-- 1 si si 16862 May 27 08:00 entitygroup.xml
-rw-rw-r-- 1 si si 62923 May 27 08:00
entitymodel_shipment.xml
-rw-rw-r-- 1 si si 171582 May 27 08:00 entitymodel.xml
[si@localhost product]$ ls -l servicedef/
total 252
-rw-rw-r-- 1 si si 1836 May 27 08:00 groups_shipment.xml
-rw-rw-r-- 1 si si 5217 May 27 08:00 secas_shipment.xml
-rw-rw-r-- 1 si si 3897 May 27 08:00 secas.xml
-rw-rw-r-- 1 si si 42967 May 27 08:00
services_facility.xml
-rw-rw-r-- 1 si si 15516 May 27 08:00
services_feature.xml
-rw-rw-r-- 1 si si 9261 May 27 08:00 services_maint.xml
-rw-rw-r-- 1 si si 9411 May 27 08:00
services_picklist.xml
-rw-rw-r-- 1 si si 19216 May 27 08:00
services_pricepromo.xml
-rw-rw-r-- 1 si si 3374 May 27 08:00
services_shipment_ups.xml
-rw-rw-r-- 1 si si 5844 May 27 08:00
services_shipment_usps.xml
-rw-rw-r-- 1 si si 29717 May 27 08:00
services_shipment.xml
-rw-rw-r-- 1 si si 16205 May 27 08:00 services_store.xml
-rw-rw-r-- 1 si si 9817 May 27 08:00 services_view.xml
-rw-rw-r-- 1 si si 56540 May 27 08:00 services.xml
The webapp/ directory holds the web front end applications. A look inside shows that this
application actually has two web applications, catalog and facility:
[si@localhost product]$ ls -l webapp/

total 8
drwxrwxr-x 18 si si 4096 May 27 08:00 catalog
drwxrwxr-x 13 si si 4096 May 27 08:00 facility
catalog/ is the OFBiz Catalog Manager, used to manage product information. facility/ is the OFBiz
Facility Manager, used to manage warehouses and inventory.
In most dynamic web pages, there are some page elements, such as page headers, navigation
bars, or shopping cart contents, that are repeated on many pages. When a visitor requests the
page, the page will usually do some preprocessing, such as retrieving data from a database, and
then present it to the user on a display page. In PHP, this is usually done by a SQL query first and
then HTML code which presents the results of the query.
With OFBiz, pages are divided into smaller pieces which are re-combined to create the final product.
Thus, many pages can share common elements such as page headers, sidebars, and navigation
bars. This is called the "decorator pattern." There is a further separation of the activities of a page
into "actions," such as getting data from a database, and "presentation," the display of that data
to the visitor.
The "actions" in OFBiz are written in beanshell scripts, while the "presentation" is written
in Freemarker template pages. Beanshell (.bsh) is a scripted version of Java, while Freemarker (.ftl)
is a templating language that is used in OFBiz to create HTML or XSL:FO pages.
So here are the contents immediately inside a web application. The sub-directories hold the pieces
of Freemarker pages:
[si@localhost product]$ ls -l webapp/catalog/

total 80
drwxrwxr-x 3 si si 4096 May 27 08:00 category
-rw-rw-r-- 1 si si 1866 May 27 08:00
ChooseTopCategory.ftl
drwxrwxr-x 3 si si 4096 May 27 08:00 config
drwxrwxr-x 3 si si 4096 May 27 08:00 error
-rw-rw-r-- 1 si si 1552 May 27 08:00 FastLoadCache.ftl
drwxrwxr-x 3 si si 4096 May 27 08:00 feature
drwxrwxr-x 3 si si 4096 May 27 08:00 find
drwxrwxr-x 3 si si 4096 May 27 08:00 includes
-rw-rw-r-- 1 si si 44 May 27 08:00 index.jsp
drwxrwxr-x 3 si si 4096 May 27 08:00 lookup
-rw-rw-r-- 1 si si 4575 May 27 08:00 main.ftl
drwxrwxr-x 3 si si 4096 May 27 08:00 price
drwxrwxr-x 3 si si 4096 May 27 08:00 product
drwxrwxr-x 3 si si 4096 May 27 08:00 promo
drwxrwxr-x 3 si si 4096 May 27 08:00 reviews
drwxrwxr-x 3 si si 4096 May 27 08:00 store
drwxrwxr-x 3 si si 4096 May 27 08:00 thesaurus
drwxrwxr-x 4 si si 4096 May 27 12:21 WEB-INF
Most of the web application's page sections are put into different directories depending on their
function. The includes/ directory holds many of the pieces of a web application. The WEB-INF
directory is a "private" directory for files which should not be viewed directly by visitors. It holds
files for controlling the flow logic and actions of this web application:
[si@localhost product]$ ls -l webapp/catalog/WEB-INF/

total 132
drwxrwxr-x 13 si si 4096 May 27 08:00 actions
-rw-rw-r-- 1 si si 117202 May 27 08:00 controller.xml
-rw-rw-r-- 1 si si 4442 May 27 08:00 web.xml
o controller.xml is a very important file that directs the flow of the web application. It maps
URI requests from the visitor's browser to events, services, and pages.
o web.xml contains supplemental information for the web application.
o actions/ directory has beanshell scripts that are used to process and gather data for the
pages.
The beanshell scripts in the WEB-INF/actions/ directory often mirror the Freemarker pages in the
other directories. For example:
[si@localhost product]$ ls -l webapp/catalog/product/

total 240
-rw-rw-r-- 1 si si 6886 May 27 08:00
ApplyFeaturesFromCategory.ftl
-rw-rw-r-- 1 si si 2099 May 27 08:00
CreateVirtualWithVariantsForm.ftl
-rw-rw-r-- 1 si si 16552 May 27 08:00
EditProductAssoc.ftl
-rw-rw-r-- 1 si si 3813 May 27 08:00
EditProductAttributes.ftl
-rw-rw-r-- 1 si si 1407 May 27 08:00
EditProductContentContent.ftl
-rw-rw-r-- 1 si si 14132 May 27 08:00
EditProductContent.ftl
-rw-rw-r-- 1 si si 6126 May 27 08:00
EditProductDupForm.ftl
-rw-rw-r-- 1 si si 4519 May 27 08:00
EditProductFacilities.ftl
-rw-rw-r-- 1 si si 5273 May 27 08:00
EditProductFacilityLocations.ftl
-rw-rw-r-- 1 si si 13625 May 27 08:00
EditProductFeatures.ftl
-rw-rw-r-- 1 si si 5008 May 27 08:00
EditProductGlAccounts.ftl
-rw-rw-r-- 1 si si 4200 May 27 08:00
EditProductGoodIdentifications.ftl
-rw-rw-r-- 1 si si 13207 May 27 08:00
EditProductInventoryItems.ftl
-rw-rw-r-- 1 si si 6358 May 27 08:00
EditProductKeyword.ftl
-rw-rw-r-- 1 si si 23480 May 27 08:00
EditProductQuickAdmin.ftl
-rw-rw-r-- 1 si si 60917 May 27 08:00 ProductForms.xml
-rw-rw-r-- 1 si si 5721 May 27 08:00 ProductTabBar.ftl
-rw-rw-r-- 1 si si 6380 May 27 08:00
QuickAddVariants.ftl
[si@localhost product]$ ls -l webapp/catalog/WEB-INF/actions/product/
total 72
-rw-rw-r-- 1 si si 5862 May 27 08:00
ApplyFeaturesFromCategory.bsh
-rw-rw-r-- 1 si si 2489 May 27 08:00
ApplyFeaturesFromGroup.bsh
-rw-rw-r-- 1 si si 3548 May 27 08:00
EditProductAssoc.bsh
-rw-rw-r-- 1 si si 7490 May 27 08:00
EditProductContent.bsh
-rw-rw-r-- 1 si si 6920 May 27 08:00
EditProductContentContent.bsh
-rw-rw-r-- 1 si si 2574 May 27 08:00
EditProductFeatures.bsh
-rw-rw-r-- 1 si si 11386 May 27 12:27
EditProductInventoryItems.bsh
-rw-rw-r-- 1 si si 17166 May 27 08:00
EditProductQuickAdmin.bsh
-rw-rw-r-- 1 si si 1890 May 27 08:00
QuickAddVariants.bsh
There is not a one-to-one correspondence because the same beanshell script in actions/ can be
reused for multiple pages, and also because some pages are pieced together from multiple
Freemarker templates but require only one beanshell script.
Finally, there is one more component of an OFBiz application: the widgets/ directory:
[si@localhost product]$ ls -l widget/

total 8
drwxrwxr-x 3 si si 4096 May 27 08:00 facility
As you can see, this mirrors the contents of webapp/ from above. This is not an accident. The
widgets/ directory holds "widgets" for rendering user interface screens. OFBiz allows user interface
designs to be created as "generic screens" rather than just web pages, so they could be reused
eventually for some other platform. The widgets/ directory's contents mirror those of the webapp/,
so there are widgets for the catalog/ webapp and the facility/ webapp.
Now let's take a look at what's in a widgets directory:
[si@localhost product]$ ls -l widget/catalog/

total 176
-rwxrwxr-x 1 si si 11824 May 27 08:00 CatalogScreens.xml
-rwxrwxr-x 1 si si 19862 May 27 08:00 CategoryScreens.xml
-rw-rw-r-- 1 si si 9986 May 27 08:00 CommonScreens.xml
-rwxrwxr-x 1 si si 11122 May 27 08:00 ConfigScreens.xml
-rw-rw-r-- 1 si si 10961 May 27 08:00 FeatureScreens.xml
-rwxrwxr-x 1 si si 5937 May 27 08:00 FindScreens.xml
-rw-rw-r-- 1 si si 6695 May 27 08:00 LookupScreens.xml
-rwxrwxr-x 1 si si 4440 May 27 08:00 PriceScreens.xml
-rw-rw-r-- 1 si si 39740 May 27 08:00 ProductScreens.xml
-rwxrwxr-x 1 si si 14900 May 27 08:00 PromoScreens.xml
-rwxrwxr-x 1 si si 3682 May 27 08:00 ReviewScreens.xml
-rwxrwxr-x 1 si si 19802 May 27 08:00 StoreScreens.xml
-rwxrwxr-x 1 si si 3588 May 27 08:00
ThesaurusScreens.xml
What you see are XML definitions for various screens here. The screens tell OFBiz how to create a
screen: what pieces of common navigation elements, Freemarker page sections, and actions are
required to create a particular page.
Now you've seen how an OFBiz application is put together. Future tutorials will show you how to
develop one from scratch and customize an existing one.
Entities and Services Data Models and Business Logic in
OFBiz
This tutorial will provide a more detailed overview of how data models and business logic is defined
in Open For Business. It will show how to use beanshell with OFBiz.
Throughout this tutorial, click on any image to enlarge it.
Data Modeling with Entities
The data model of an application is a model of the physical "things" in the application, their
properties, and their relationships. Typically, data models are implementetd either with SQL or
objects or a combination of both.
OFBiz provides us with an "entity engine" which allows data models to be implemented at a higher
level of abstraction. The data model is defined in an XML file, and OFBiz provides us with a set of
generic APIs for working with the actual data: finding, creating, updating, and removing them. The
entity engine thus allows us to:
o work with the data at a higher level, rather than in lower level SQL or Java code.
o achieve complete independence from the underlying database. OFBiz will work with a large
number of commercial or open source databases.
o reduce the amount of maintenance when applications need to be changed, by centralizing
definitions and working with more generic concepts.
o avoid the overhead of object-relational persistence with a simple set of APIs.
The basic unit of the data model is an "entity," which is a discrete "thing" modeled in the data
model. Here is an example of how an entity for information about a person is
defined:
The entity is analogous to a SQL table or Java object, with various fields for specific attributes of a
person. The definition, is however, at a more abstract level. The OFBiz entity engine will start with
this definition and create the database tables, check the tables against the definitions over time,
and modify tables if needed.
The types of the fields are defined in generic types, rather than specific SQL or Java types. OFBiz
will then translate these fields to SQL types when working with the database and to Java types
when working in Java. The exact translation is determined in a fieldtype file in the
framework/entity/fieldtype/ directory: You can see the fieldtype definitions for all the different
databases on the left and the actual field mappings for MySQL and Microsoft SQL Server on the
right. Notice how different some of the SQL types can be.
The other important part of defining data models in OFBiz is creating relationships between entities.
The entity engine lets you create explicit relationships between entities based on their keys:
Relationships can be one-to-one or one-to-many and can (but does not have to) involve referential
integrity checks. Using these relationships allows you to go from one entity to another in your
application without having to remember exactly which key was involved at all times. Should the
keys used in a relationship change, it also avoids the need to make modifications throughout your
application.
(Note: OFBiz can generate the foreign-key names automatically for you, but it is good practice to
specify them yourself to avoid accidental key collisions, etc.)
In the OFBiz webtools application, you can take a look at all the entities available:
A Word about Beanshell
beanshell is a dynamic scripting language with Java syntax, and it is used extensively in OFBiz for
view layer presentation data gathering. It can also be used for debugging, testing, and prototyping.
In fact, entire services can be prototyped in beanshell and then used "as is" with the service engine
or transformed to Java code when done.
When you start OFBiz, you may have noticed these lines on your console:
Httpd started on port: 9989

Sessiond started on port: 9990
23092 (main) [ BeanShellContainer.java:109:INFO ] Started BeanShell telnet
service on 9989, 9990
23093 (main) [ BeanShellContainer.java:110:INFO ] NOTICE: BeanShell service
ports are not secure. Please protect the ports
They tell you that OFBiz has opened a beanshell container on port 9990. (WARNING: protect or
close this port on production systems.) You can telnet into this port and have full access to your
OFBiz server, allowing you to test code and monitor events. I have a bshcontainer.bsh which, once
placed in your ofbiz/ directory, can be called up with:
source("bshcontainer.bsh");
It will give you a delegator object for accessing the entity engine, a dispatcher for running services,
and an admin UserLogin entity for services which require authentication.
I prefer to telnet into beanshell from Xemacs on Linux, which allows me to edit my beanshell
commands. Unfortunately, I don't know of a good Windows telnet client. (If you do, please let me
know.)
Working with Entities
Now let's work with our entities. Telnet into beanshell and (after some preliminary experiments)
use the delegator object to access the Person entity. delegator is a GenericDelegator object with a
set of methods for finding, creating, updating, and removing data. The delegator accepts
parameters in the form of key-value pairs and translates them into actual SQL statements such as
SELECT and INSERT. It will also observe the correct SQL syntax for the particular database you are
using. Here is an example:
Above we had just found all Persons with a last name of "chen", and the delegator returned a List
of just one. Now let's take a look at a particular person record:
bsh % me = persons.get(0);
bsh % print(me.getClass().getName());
org.ofbiz.entity.GenericValue
Each entity is an object of the GenericValue class, which itself is a sub-class of GenericEntity.
GenericEntity provides us with methods to get and set values to fields, while GenericValue gives us
methods for traversing through the data model with defined relationships.
Here is an example of how to get values from fields:
bsh % print(me.getString("firstName") + " " + me.get("lastName"));

print(me.getString("firstName") + " " + me.get("lastName"));
si chen
and for setting values to fields:
bsh % me.set("memberId", "11111");

me.set("memberId", "11111");
and storing the entity:
bsh % me.store();
Now let's retrieve it again and see if our change was effecive:
bsh % me2 = delegator.findByPrimaryKeyCache("Person",

UtilMisc.toMap("partyId", "10010"));
bsh % print(me2.get("firstName") + " " + me2.get("lastName") + " " +
me2.get("memberId"));
si chen 11111
Notice the different find method here--I was able to use the primary key field to get to the entity
directly. The entity engine also caches values for you, so I used a cached find method this time.
You can also traverse from one entity to another. For example, there is a one-to-one relationship
from Person to Party, so you can get the Party for a Person like so: bsh %
print(me2.getRelatedOne("Party"));
[GenericEntity:Party][createdByUserLogin,null()][createdDate,2005-06-07
06:42:57.919(java.sql.Timestamp)]
[createdStamp,2005-06-07
06:42:58.113(java.sql.Timestamp)][createdTxStamp,2005-06-07
[externalId,null()][lastModifiedByUserLogin,null()][lastModifiedDate,2005
-06-07 06:42:57.919(java.sql.Timestamp)]
[lastUpdatedStamp,2005-06-07
06:42:58.113(java.sql.Timestamp)][lastUpdatedTxStamp,2005-06-07
[partyId,10010(java.lang.String)][partyTypeId,PERSON(java.lang.String)]
Any Party can have many UserLogins, so you can go a step further to get the UserLogins for a
Person through Party: bsh % print(me2.getRelatedOne("Party").getRelated("UserLogin"));
print(me2.getRelatedOne("Party").getRelated("UserLogin"));
[[GenericEntity:UserLogin][createdStamp,2005-06-07
[createdTxStamp,2005-06-07
06:42:58.113(java.sql.Timestamp)][currentPassword,(java.lang.String)]
[disabledDateTime,null()][enabled,null()][hasLoggedOut,null()]
[isSystem,null()][lastCurrencyUom,null()][lastLocale,null()][lastUpdatedS
tamp,2005-06-07 06:42:58.343(java.sql.Timestamp)]
[lastUpdatedTxStamp,2005-06-07
06:42:58.113(java.sql.Timestamp)][partyId,10010(java.lang.String)][passwo
rdHint,null()]
[successiveFailedLogins,null()][userLoginId,sichen0607@graciousstyle.com(
java.lang.String)]]
Finally, an unusually complicated one for getting the shipping address of a person:
bsh %
print(me2.getRelatedOne("Party").getRelatedByAnd("PartyContactMechPurpose
", UtilMisc.toMap("contactMechPurposeTypeId",
"SHIPPING_LOCATION")).get(0).getRelatedOne("ContactMech").getRelatedOne("
PostalAddress"));
[GenericEntity:PostalAddress][address1,11986 Foxboro
Dr(java.lang.String)][address2,null()][attnName,null()]
[city,Los
Angeles(java.lang.String)][contactMechId,10000(java.lang.String)]
[countryGeoId,USA(java.lang.String)]
[createdStamp,2005-06-07
06:42:58.911(java.sql.Timestamp)][createdTxStamp,2005-06-07
[directions,null()][lastUpdatedStamp,2005-06-07
[lastUpdatedTxStamp,2005-06-07 06:42:58.808(java.sql.Timestamp)]
[postalCode,90049(java.lang.String)][postalCodeExt,null()][postalCodeGeoI
d,null()]
[stateProvinceGeoId,CA(java.lang.String)][toName,si
chen(java.lang.String)]
Notice how you can also filter results from getting related entities.
Business Logic and Services
The business logic tier in OFBiz is similar in philosophy to the way the data modeling is done. We
create generic definitions of business logic, implement it in a variety of ways, and access it with a
generic set of APIs. This is all done via a service engine. OFBiz is thus built on a Service Oriented
Architecture (SOA).
The first step is to define your services in an XML file:
Here, services are declared, and they can be implemented in either Java (engine="java") or the
OFBiz minilang (engine="simple".) Like Java, you can also define generic "interface" services
which are implemented by other services. Each service has input and output parameter fields, and
the fields have Java types. But the service engine goes a step further: you can also link a service
directly to an entity, and OFBiz will figure out the parameters and requisite types for you. This not
only saves a lot of typing but makes it unnecessary to modify a large number of services when an
entity changes.
You can browse the services in OFBiz with the "Services Available" tool in Web Tools:
Services can be implemented in Java, and Java services follow a standard pattern, like this:
Every Java service is a public static method which takes two parameters, a DispatchContext and a
Map called context, and returns a Map. The dispatch context will pass along tools such as the
delegator and dispatcher (for running services, see below.) The context is a Map of all the
parameters. The method also returns a Map with status of service (success or fail) and return
parameters matching those defined in the XML file.
OFBiz also provides a scripting language called minilang or simple-method, which allows for more
efficient coding of many tasks. It is specifically designed to work with the OFBiz entity and service
engines and perform tasks such as look up, create, run services, or check permissions with simple
directives. It is also interpreted and allows for iterative debugging. Here is an example:
Finally, OFBiz services can be implemented in a number of other Java scripting languages, such as
Jython, beanshell, Javascript, and potentially any BSF compatible scripting language. The idea is to
work with the best tool for the project, given the nature of the task and background of your team.
We call services through an object (usually) called dispatcher, which is of a sub-class of

the LocalDispatcher interface:
esh % result = dispatcher.runSync("createPerson",

UtilMisc.toMap("firstName", "A", "lastName", "Person"));
bsh % print(result);
[partyId=10050, responseMessage=success]
Here we have just called a service synchronously (in the same thread) to create a Person. We could
have also asked OFBiz to run the service asynchronously, or on a separate thread in parallel with
our current task.
Some services require validation, and a UserLogin value must be passed in:
bsh % result = dispatcher.runSync("updatePerson", UtilMisc.toMap("partyId",

"10050", "nickname", "some bloke"));
// Error: // Uncaught Exception: Method Invocation dispatcher.runSync : at
Line: 26 : in file: : dispatcher .runSync ( "updatePerson" , UtilMisc .toMap
( "partyId" , "10050" , "nickname" , "some bloke" ) )
Target exception: org.ofbiz.service.ServiceAuthException: User

authorization is required for this service: updatePerson
org.ofbiz.service.ServiceAuthException: User authorization is required for

this service: updatePerson
at
org.ofbiz.service.ServiceDispatcher.runSync(ServiceDispatcher.java:309)
at
org.ofbiz.service.ServiceDispatcher.runSync(ServiceDispatcher.java:212)
at
org.ofbiz.service.GenericDispatcher.runSync(GenericDispatcher.java:110)
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
at
sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java
:39)
at
sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorI
mpl.java:25)
at java.lang.reflect.Method.invoke(Method.java:324)
at bsh.Reflect.invokeOnMethod(Reflect.java:117)
at bsh.Reflect.invokeObjectMethod(Reflect.java:91)
at bsh.Name.invokeMethod(Name.java:689)
at bsh.BSHMethodInvocation.eval(BSHMethodInvocation.java:55)
at bsh.BSHPrimaryExpression.eval(BSHPrimaryExpression.java:69)
at bsh.BSHAssignment.eval(BSHAssignment.java:58)
at bsh.Interpreter.run(Interpreter.java:436)
at bsh.util.SessiondConnection.run(Sessiond.java:97)
bsh % result = dispatcher.runSync("updatePerson", UtilMisc.toMap("partyId",
"10050", "nickname", "some bloke", "userLogin", admin));
bsh % print(result);
[successMessage=person.update.success, responseMessage=success]
bsh % bloke = delegator.findByPrimaryKey("Person",
UtilMisc.toMap("partyId", "10050"));
bsh % print(bloke.get("nickname"));
some bloke
And we see that a new Person was created and updated.
If you do not have the userLogin object but have a username and password, the magic words are
login.username and login.password, like this:
result = dispatcher.runSync("updatePerson", UtilMisc.toMap("partyId",

"10050", "nickname", "some bloke", "login.username", "admin",
"login.password", "ofbiz"));
This is appropriate if you need to call the service remotely such as from an external application via
SOAP or XML-RPC.
A final note: OFBiz will wrap services automatically in transactions, so there is no need (usually) to
write your own.
Mutually Aware Interactions
The most powerful feature of the OFBizFramework is the fact that all the tools work together,
including the entity engine, service engine, web controller, and front end user screen and form
generation tools. For example, you can define an entity, and the service engine will automatically
figure out what fields it needs. The controller can automatically parse user form inputs into the
service engine. Even user screens can be automatically generated.
The result is a drastic reduction in the amount of duplicate code that must be written for normal
applications. This not only reduces initial development time and costs but also long-term
maintenance costs and risks, as business requirements change.
For more information
Visit the Documents page on ofbiz.org for more information on the entity and service engines,
minilang, and various APIs.
OFBiz Eclipse Debugging OFBiz
Preliminary Setup
If you have not already done so, import ofbiz into Eclipse with File > Import > "Existing Projects
into Workspace". Note that the name of the project and its name in .project file must be the same.
The next step is to enable Eclipse to work on your .xml, .ftl, and .bsh files. First, install an XML
editor such as the free XMLBuddy. Then, install the Freemarker Eclipse plug-in. Finally, go to
Windows > Preferences > General > Editors > File Associations and add "*.bsh" and associate it
with the Scrapbook editor.
You should also set your editors to be compatible with OFBiz coding convention. For Java files, go
to Windows > Preferences > Java > Code Style > Formatter and create a new profile. Set your tabs
to 4 spaces. Similarly, go to Windows > Preferences > XMLBuddy > Formatting and click on "Use
spaces for tabs", or configure your XMLZ editor likewise.
You can toggle between code view and directory/file view by switching Eclipse from "Java
Perspective" our "Java Browsing" and "Resources". If you have new components, add them to
your .classpath file as a <classpathentry> so they can be viewed in the Java views.
Java Debugging with Eclipse
Click on the green bug icon on the Eclipse toolbar, or click on "Run" on the top menu bar, then
"Debug". Then click on "Java Application", click on "New" to create a new configuration for OFBIZ.
Type in the start class name. Then click "Apply" and "Close".
Now you need to fix all of these problems Eclipse has found (see box at the bottom):
The most common problem involves missing class and libraries from the build classpath, which you
add with Project > Properties > Java Build Path:
You may also have to exclude third party source file by editing .classpath in
eclipse/workspace/ofbiz and adding <classpathentry
excluding="org/ofbiz/securityext/thirdparty/truition/*" kind="src"
path="applications/securityext/src"/>
You have to add the OFBiz base/config directory to your class path. Use Project > Properties > Java
Build Path > Libraries > [Add Class Folder] and add the base/config directory:
This is what it looks like with base/config added:
Now you need to add your JDBC library JARs to the Eclipse classpath. Use Project > Properties >
Java Build Path > Libraries > [Add External JARs] and select the JARs from
ofbiz/framework/entity/lib/jdbc. Here, we add the JARs for the embedded derby database:
You also need to add the JARs for Tomcat from ofbiz/framework/catalina/lib. Note: Current
versions of OFBiz have more JARs than on this screenshot. Add them all.
You may need to do this for compiling JSP's:
Now edit base/config/ofbiz-containers.xml and comment out both the rmi-dispatcher and the
rmi-print-server (not shown here):
Now OFBiz should run in Eclipse. Here are some screenshots of debugging OFBiz with Eclipse:
Miscellaneous Notes
When you update your code with an $ svn update, Eclipse does not know that new files are
available. Thus, you may start to have build problems. Do a File > Refresh from within Eclipse to
bring it up to date.
Make sure that ofbiz/ is not in your Project > Properties > Java Build Path > Source. Only
ofbiz/applications/.., ofbiz/framework/.., ofbiz/hot-deploy/.. directories should be there, or you'll
get an error like:
Cannot nest output folder "hot-deploy/crmsfa/src" inside "ofbiz/"

Examples
强烈推荐想快速入门 OFBiz 的开发人员，先照着这几个例子做几遍。

Hello World Tutorials Fixes for More Recent OFBIZ Versions
不少人按照网上的文档做，没想到版本变化了。
The original Hello World tutorials were written in June 2005, and since then there have been some
significant changes to the structure of the OFBiz directories after opentaps 0.9.x releases. If you
are trying the Hello World tutorials on a later version of OFBiz or opentaps, you must make the
following changes necessary:
First, each web.xml file in the hello_/webapp/hello_/WEB-INF/ must be changed so that:
org.ofbiz.securityext.login.LoginEventListener
is replaced by:
org.ofbiz.webapp.control.LoginEventListener
Second, the build.xml file in the hello3/ directory needs to have the lines:
<fileset dir="../../base/lib" includes="*.jar"/>

<fileset dir="../../base/build/lib" includes="*.jar"/>
changed to:
<fileset dir="../../framework/base/lib" includes="*.jar"/>

<fileset dir="../../framework/base/build/lib" includes="*.jar"/>
Third, if you are using opentaps 1.0.0 or later, you must edit the file
hot-deploy/component-load.xml and add the hello applications there, like this:
<load-component component-location="${ofbiz.home}/hot-deploy/hello1"/>
This additional step is required because there are many opentaps modules in the hot-deploy/
directory which are not part of OFBIZ, and the component-load.xml file controls the correct
sequence of loading. If you are just using OFBIZ, you do not need to do this.

OFBiz Hello World Application Example
This tutorial will show you how to build a very simple OFBiz application. You will see how OFBiz
application components and web applications are created, how web pages are created, and how an
OFBiz controller helps direct web requests.
This tutorial was done on Linux, but OFBiz and these examples will work with any operating system
with a Java SDK.
Creating an Application
In OFBiz, every application sits inside its own fully contained component, so your first step is to
create a component. A component can sit inside the framework/, application/, specialized/, or
hot-deploy/ directory. The advantage of the hot-deploy/ directory is that components here are
loaded automatically when OFBiz starts. So, for our first step, let's create a sub-directory in
hot-deploy/ for our new component, which we'll call hello1:
sichen@linux:~/eclipse/workspace/ofbiz> ls -l hot-deploy/
total 4
drwxrwxr-x 4 sichen users 136 2005-05-19 07:16 hello1
-rw-r--r-- 1 sichen users 127 2005-06-02 15:19 README.txt
(Note that everything in this tutorial is inside my eclipse/workspace/ directories because I use
the Eclipse IDE, but in fact you can put ofbiz anywhere, and the directory structure is the same.)
Inside your new application component, there must be an ofbiz-component.xml file to tell OFBiz
about your applicaton component: its data model (tables), business logic (services) and workflow,
UI layer (web or GUI applications), any seed data it may have, and what other resources it requires.
You can take a look at the ofbiz-component.xml files in other applications, which can be quite
complex. For hello1, we just need to create a simple one that looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<ofbiz-component name="hello1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://www.ofbiz.org/dtds/ofbiz-component.
xsd">
<resource-loader name="main" type="component"/>
<webapp name="hello1"
title="My First OFBiz Application"
server="default-server"
location="webapp/hello1"
mount-point="/hello1"
app-bar-display="false"/>
</ofbiz-component>
What is this file telling OFBiz?
o That we have a component named "hello1"

o That it should use the "main" resource-loader
o That it has one web application, also called "hello1"
o The "hello1" web application should use the "default-server" web server
o The "hello1" web application is inside the webapp/ directory
o The "hello1" web application should be mounted at a URI of "/hello1"
o We don't want the app-bar, which shows all the applications available in OFBiz, to be
displayed in our web app
Creating a Web Application
A web application is a UI component that interacts with the user over the web. An OFBiz application
component can have several UI components, some of which are webapps.
Now that you have configured your new application, the next step is to create a webapp/ directory
for its web applications. Inside this directory, create a hello1/ directory for the "hello1" web app
you just named. When you are done, it should look like this:
sichen@linux:~/eclipse/workspace/ofbiz/hot-deploy/hello1> ls -l
total 4
-rw------- 1 sichen users 1733 2005-06-02 15:57 ofbiz-component.xml
drwxrwxr-x 3 sichen users 72 2005-06-02 15:54 webapp
sichen@linux:~/eclipse/workspace/ofbiz/hot-deploy/hello1> ls -l webapp/
total 0
drwxrwxr-x 3 sichen users 96 2005-06-02 16:10 hello1
Now we are ready to work inside the webapp/hello1 directory and create a web application.
Remember that OFBiz is a Model-View-Controller framework, which means that a controller
manages visitor requests and routes them to the appropriate pages and actions. Thus, separate
pages and a master controller are needed.
Typically for Java web applications, pages which are viewable by visitors, such as HTML or JSPs,
are inside a webapp/ directory, while private files, such as XML configuration files or Java servlets,
are hidden inside a WEB-INF/ directory.
This is the case with OFBiz as well. We'll first create a WEB-INF/ directory and then create just one
file to be displayed to our visitors, which we'll call main.ftl, for Freemarker template file.
(Freemarker is a very easy, intuitive templating language that allows you to put basic controls,
such as loops and if-then-else, around your HTML.) main.ftl is just a straightforward HTML file:
<html>
<head>
<title>Hello World</title>
</head>
<body>
<h1>HELLO</h1>
<p>Hello world!</p>
</body>
</html>
Now this would be your contents of your webapp/hello1/ directory:
sichen@linux:~/eclipse/workspace/ofbiz/hot-deploy/hello1/webapp/hello1>
ls -l
total 4
-rw------- 1 sichen users 107 2005-06-02 16:23 main.ftl
drwxrwxr-x 2 sichen users 104 2005-06-02 16:17 WEB-INF
The final step is to create the files to configure the webapp. At a minimum, an OFBiz web
application requires two configuration files, a controller.xml and a web.xml. controller.xml tells
OFBiz what to do with various requests from visitors: what actions to take and what pages to
render. web.xml tells OFBiz what resources (database and business logic access) are available for
this web application and how to handle web-related issues, such as welcome pages, redirects, and
error pages.
If you're starting a new application, both files can be copied from the WEB-INF/ directory of an
existing application. I copied mine over from the catalog manager. web.xml can almost be used in
place, with no modification, like this:
<?xml version="1.0"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application
2.3//EN" "http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
<display-name>Hello 1</display-name>
<description>The First Hello World Application</description>
<context-param>
<param-name>entityDelegatorName</param-name>
<param-value>default</param-value>
<description>The Name of the Entity Delegator to use, defined in
entityengine.xml</description>
</context-param>
<context-param>
<param-name>localDispatcherName</param-name>
<param-value>hello1</param-value>
<description>A unique name used to identify/recognize the local
dispatcher for the Service Engine</description>
</context-param>
<context-param>
<param-name>serviceReaderUrls</param-name>
<param-value>/WEB-INF/services.xml</param-value>
<description>Configuration File(s) For The Service
Dispatcher</description>
</context-param>
<filter>
<filter-name>ContextFilter</filter-name>
<display-name>ContextFilter</display-name>
<filter-class>org.ofbiz.webapp.control.ContextFilter</filter-class>
<init-param>
<param-name>disableContextSecurity</param-name>
<param-value>N</param-value>
</init-param>
<init-param>
<param-name>allowedPaths</param-name>
<param-value>/control:/select:/index.html:/index.jsp:/default.html:
/default.jsp:/images:/includes/maincss.css</param-value>
</init-param>
<init-param>
<param-name>errorCode</param-name>
<param-value>403</param-value>
</init-param>
<init-param>
<param-name>redirectPath</param-name>
<param-value>/control/main</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>ContextFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
<listener><listener-class>
org.ofbiz.webapp.control.ControlEventListener</listener-class></listener>
<listener><listener-class>
org.ofbiz.webapp.control.LoginEventListener</listener-class></listener>


<servlet>
<servlet-name>ControlServlet</servlet-name>
<display-name>ControlServlet</display-name>
<description>Main Control Servlet</description>
<servlet-class>org.ofbiz.webapp.control.ControlServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>ControlServlet</servlet-name>
<url-pattern>/control/*</url-pattern>
</servlet-mapping>
<session-config>
<session-timeout>60</session-timeout> 
</session-config>
<welcome-file-list>
<welcome-file>index.jsp</welcome-file>
<welcome-file>index.html</welcome-file>
<welcome-file>index.htm</welcome-file>
</welcome-file-list>
</web-app>
The controller.xml can also be copied but needs to be modified to reflect your needs: what your
URI requests you want to allow in your webapp, and how you want OFBiz to process them. Here is
the controller modified for hello1:
<?xml version="1.0" encoding="UTF-8" ?>
<site-conf xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://www.ofbiz.org/dtds/site-conf.xsd">
<description>First Hello World Site Configuration File</description>
<owner>Open For Business Project (c) 2005 </owner>
<errorpage>/error/error.jsp</errorpage>
<handler name="java" type="request"

class="org.ofbiz.webapp.event.JavaEventHandler"/>
<handler name="soap" type="request"
class="org.ofbiz.webapp.event.SOAPEventHandler"/>
<handler name="service" type="request"
class="org.ofbiz.webapp.event.ServiceEventHandler"/>
<handler name="service-multi" type="request"
class="org.ofbiz.webapp.event.ServiceMultiEventHandler"/>
<handler name="simple" type="request"
class="org.ofbiz.webapp.event.SimpleEventHandler"/>
<handler name="ftl" type="view"

class="org.ofbiz.webapp.ftl.FreeMarkerViewHandler"/>
<handler name="jsp" type="view"
class="org.ofbiz.webapp.view.JspViewHandler"/>
<handler name="screen" type="view"
class="org.ofbiz.widget.screen.ScreenWidgetViewHandler"/>
<handler name="http" type="view"

class="org.ofbiz.webapp.view.HttpViewHandler"/>
<preprocessor>


<event type="java" path="org.ofbiz.securityext.login.LoginEvents"
invoke="checkExternalLoginKey"/>
</preprocessor>
<postprocessor>


</postprocessor>


<request-map uri="main">
<response name="success" type="view" value="main"/>
</request-map>



<view-map name="error" page="/error/error.jsp"/>
<view-map name="main" type="ftl" page="main.ftl"/>

</site-conf>
The OFBiz controller allows you to specify:
o handlers, which are Java classes that handle either requests or produce views in various
formats. For example, the handler for "java" events routes requests to a Java servlet, while
the "service" handler routes requests to the service engine, automatically parsing visitor
input into service input parameters. The various view requests produce output to the
browser based on Freemarker templates, velocity, JSP, or the OFBiz screen widget.
o pre- and post-processors, which are servlets that are run before and after every web
request.
o request mappings, which map URI requests to either request or view handlers. Request
mappings can also re-direct to other request mappings, allowing requests to be chained
together.
o view mappings, which generate output to the visitor by specifying where the page is
located. By default, view mappings reference files starting from the current web
application's directory, in this case, webapp/hello1/.
In this simple controller, there are no pre- or postprocessor events to be run. Only one request is
allowed, "/main", and it leads us to a view called "main", which uses main.ftl we created earlier to
generate output back to the visitor.
Running our application
Now we are ready. Let's run our first application:
sichen@linux:~/eclipse/workspace/ofbiz> ./startofbiz.sh
sichen@linux:~/eclipse/workspace/ofbiz> tail -f logs/console.log
In Linux, the startup script runs OFBiz in the background, so you need tail to see the console output.
In Windows, just do:
c:\ofbiz> startofbiz.bat
and the output is displayed on your screen. The log file is quite lengthy but you will see these lines:
...
1607 (main) [ ComponentContainer.java:153:INFO ] Auto-Loading component
directory : [/home/sichen/eclipse/workspace/ofbiz/hot-deploy]
1619 (main) [ UtilXml.java:242:DEBUG] XML Read 0.011s:
file:/home/sichen/eclipse/workspace/ofbiz/hot-deploy/hello1/ofbiz-compone
nt.xml
1620 (main) [ ComponentContainer.java:209:INFO ] Loading component :
[hello1]
...
18571 (main) [ ContextFilter.java:300:INFO ] [ContextFilter.init]
Getting Entity Engine Delegator with delegator name default
18573 (main) [ ServiceDispatcher.java:168:INFO ] Registered dispatcher:
hello1
18575 (main) [ GenericDispatcher.java:85 :INFO ] [LocalDispatcher] :
Created Dispatcher for: hello1
18577 (main) [ ControlServlet.java:74 :INFO ] [ControlServlet.init]
Loading Control Servlet mounted on path
/home/sichen/eclipse/workspace/ofbiz/hot-deploy/hello1/webapp/hello1/
18578 (main) [ RequestHandler.java:89 :INFO ] [RequestHandler
Loading...]
jndi:/0.0.0.0/hello1/WEB-INF/controller.xml
18588 (main) [ ConfigXMLReader.java:552:INFO ] ConfigMap Created: (4)
records in 0.0010s
18588 (main) [ ConfigXMLReader.java:622:INFO ] HandlerMap Created: (2)
records in 0.0s
18589 (main) [ ConfigXMLReader.java:302:INFO ] RequestMap Created: (1)
records in 0.0s
18589 (main) [ ConfigXMLReader.java:411:INFO ] ViewMap Created: (2)
records in 0.0s
...
21204 (main) [ CatalinaContainer.java:238:INFO ] Connector AJP/1.3 @ 8009
- not-secure [org.apache.jk.server.JkCoyoteHandler] started.
21204 (main) [ CatalinaContainer.java:235:INFO ] Connector HTTP/1.1 @ 8080
- not-secure [org.apache.coyote.http11.Http11Protocol] started.
21205 (main) [ CatalinaContainer.java:235:INFO ] Connector TLS @ 8443 -
secure [org.apache.coyote.http11.Http11Protocol] started.
21209 (main) [ CatalinaContainer.java:242:INFO ] Started Apache
Tomcat/5.5.9
Httpd started on port: 9989
Sessiond started on port: 9990
21467 (main) [ BeanShellContainer.java:109:INFO ] Started BeanShell telnet
service on 9989, 9990
21467 (main) [ BeanShellContainer.java:110:INFO ] NOTICE: BeanShell service
ports are not secure. Please protect the ports
31903 (org.ofbiz.service.jms.JmsListenerFactory@996b65)
[ JmsListenerFactory.java:82 :INFO ] JMS Listener Factory Thread Finished;
All listeners connected.
The first little block shows OFBiz auto-loading the hello1 component from within hot-deploy/. The
second block shows it setting up the hello1 webapp, getting a delegator (for database access), a
dispatcher (for running services), and loading up the controller. The last block is what you will see
when all the webapps are loaded and Tomcat, the default embedded web server, is started.
From a browser, type in:
http://localhost:8080/hello1/control/main
and you will see this.
Final Touchups
Looks like we're done... but not yet. Try typing this in your browser:
http://localhost:8080/hello1/
and you will get this. The problem is that /control is a specific request to the control servlet through
the web server, and there is no index page at the root of the webapp. This is simple to fix: just copy
an index.jsp from one of the other webapps into /webapp/hello1/. The index.jsp just has one line:
cat index.jsp
Now if you try it again, http://localhost:8080/hello1/ will also get you to the right page.
One last thing to try, type in:
http://localhost:8080/hello1/control/nonsense
You'd get a blank screen, because there is no error page right now. The location of your error page
is specified in the beginning of your controller.xml above. You will need to make or copy over a
/webapp/hello1/error/error.jsp page to show an error message to your visitors. It looks like this:
cat error/error.jsp
<%@ page import="org.ofbiz.base.util.*" %>

<html>
<head>
<title>Open For Business Message</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head>
<% String errorMsg = (String) request.getAttribute("_ERROR_MESSAGE_"); %>
<body bgcolor="#FFFFFF">
<div align="center">
<br/>
<table width="100%" border="1" height="200">
<tr>
<td>
<table width="100%" border="0" height="200">
<tr bgcolor="#CC6666">
<td height="45">
<div align="center"><font face="Verdana, Arial, Helvetica,
sans-serif" size="4" color="#FFFFFF"><b>:ERROR MESSAGE:</b></font></div>
</td>
</tr>
<tr>
<td>
<div align="left"><font face="Verdana, Arial, Helvetica,
sans-serif" size="2"><%=UtilFormatOut.replaceString(errorMsg, "\n",
"<br/>")%></font></div>
</td>
</tr>
</table>
</td>
</tr>
</table>
</div>
<div align="center"></div>
</body>
</html>
/html>
Now try the "nonsense" request again, and you should get this page. Note that this is a very
different error page: it is not from Apache Tomcat, like the first one you got, but from OFBiz. This
is because with "/control" in your URI (and the re-direct even if you didn't have it), every request
is being processed by the OFBiz controller now.
This is the final content of your webapp directory:
ls -l
total 8
drwxr-xr-x 2 sichen users 144 2005-06-03 06:01 error
-rw-r--r-- 1 sichen users 44 2005-06-03 05:52 index.jsp
-rw------- 1 sichen users 1355 2005-06-02 16:26 main.ftl
drwxrwxr-x 2 sichen users 232 2005-06-03 05:58 WEB-INF
ls -l error/
total 4
-rw-r--r-- 1 sichen users 1003 2005-06-03 05:55 error.jsp
Click to see the complete files for this application.

Conclusions
So now you have created a fully self-contained ofbiz application, with its webapp, controller, page,
and error page. This sure was a lot of work to display a simple web page. Obviously, if that's all you
needed, OFBiz is way too complicated. But chances are, that's never all you needed to do. In future
tutorials, we'll see how you can use OFBiz applications to develop your complex applications with
a lot of different tables, pages, and complicated business logic. Then you will see the advantages
of the OFBiz framework.
Extending your web app with screen‐widget, decorator, and

actions
Now you've made your first web application. In the real world, though, you'd probably be creating
applications with many, many pages which performed useful tasks. The OFBiz screen-widget
allows you to create web apps which stitch together many pieces ("decorator pattern") and
perform actions such as gathering and analyzing data ("actions.")
Throughout this tutorial, click on any image to enlarge it.
In this tutorial, we'll extend Hello World 1 to a second application, hello2. The first step is to copy
hello1 into hello2 and change the names of the "hello1" webapp to "hello2", as well as references
to it in ofbiz-component.xml:
Creating Screens
The OFBiz screen-widget is used to put together complex pages with many smaller pieces of
display elements. (If you've used earlier versions of OFBiz, it replaces JPublish and the regions
framework.)
The first step is to create an includes/ directory in your webapp and create the headers and footers
there. If you want to use a common stylesheet and graphics, this is a good place to put it. You will
also want to remove the same code from the main.ftl:
The second step is to stitch these pieces together using the screen-widget. Create a widget/
directory inside hello2/, next to webapp/. Inside widget/, create an XML file to define your screens:
sichen@linux:~/eclipse/workspace/ofbiz/hot-deploy/hello2> ls -l
total 4
-rw------- 1 sichen users 1747 2005-06-09 16:28 ofbiz-component.xml
drwxrwxr-x 3 sichen users 72 2005-06-09 16:07 webapp
drwxr-xr-x 2 sichen users 80 2005-06-09 17:02 widget
sichen@linux:~/eclipse/workspace/ofbiz/hot-deploy/hello2> ls -l widget/
total 4
-rw-r--r-- 1 sichen users 720 2005-06-09 17:02 HelloScreens.xml
The simplest screen definition is one which puts together several ftl pages together:
ERRATA:The screen shown uses the older DTD for the screen-widget, rather than the correct
xmlns.
The final step is to reference tour screen definition rather than the Freemarker template directly in
your controller:
Now we're done! If you type in
http://localhost:8080/hello2/control/main
in your browser window, you will get this.
By allowing you to compose a page with many pieces, the screen-widget will help you as you build
more complex applications.
Decorating Your Page
The decorator pattern allows you to piece a page together using many different sections, thus
allowing you to reuse those sections across multiple pages. For example, you can have separate
pages for your header, navigation bar, news panels, promotion offers, and footers.
For example, let's say that you wanted to create several pages with the same header and footer
but different content. The screen-widget allows you to do this by creating multiple screens which
re-use the same display element. To get started, first we create multiple requests and views in the
controller.xml:
Next we create the additional pages and screens. In the screen-widget XML file, you can just copy
each screen definition and change main.ftl to your page.
In the pages themselves, you no longer have to put in repetitive elements.
Note the <@ofbizUrl> tag in header.ftl (bottom.) This is used to generate your URL. These pages
look like this.
As you build larger sites, however, repetitive layout commands can be a maintenance problem.
Fortunately, the OFBiz screen-widget goes a step further by allowing you to define a template
which is repeated for many screens. You do this by declaring a <decorator-section-include> inside
a template screen (usually called a "CommonDecorator"). Then, in your other screens, you
reference the template screen with a and declare their own content with a tag. This is what it would
look like:
The web pages generated look the same as before. If, however, you got a request to, say, put a
legal disclaimer on all the pages, it would be as simple as modifiying the layout of the
CommonDecorator.
Adding Actions
Now you've seen the basics of building static sites with OFBiz. The next step is to mix in dynamic
content. Typically, most web scripting languages allow you to put code on the page to do this.
Freemarker allows you to do this as well, which is how I put in a date in the header. The creators
of Freemarker, however, discourage this because they felt it would lead to pages which are overly
complicated.
OFBiz avoids this problem by separating layout from actions or code, which gather and prepare
data. By separating actions and presentation of a web page, you can allow separate people with
different skills (programming vs design) to work on a web page. You can also reuse the same code
for generating multiple views, such as a web page or a PDF of the same content.
To do this, you would first create an actions/ directory inside your WEB-INF directory. Then you
would put in a beanshell script which would perform your actions. The beanshell script here is like
a Java servlet, only it is dynamically typed and interpreted (rather than compiled.) Also, if you
want to put objects back into the Freemarker pages to be displayed, you would put them into a Map
(already created for you) called "context". Finally, you would need to declare this action for your
screen, a new one that I've created here:
I also created an entry for it in controller.xml.
A lot is happening here. In HelloScreens.xml, you created a screen which uses people.ftl for
presentation and people.bsh for actions related to the page, which in this case is data gathering.
people.bsh is a simple script which got a delegator, looked up all the Person entities, and then put
them into the context. (OFBiz puts this delegator into the request for you.) Finally, on the bottom,
people.ftl displays all the names. (This is a good example of some of Freemarker's syntax.)
And this is what you will see.
There is also a way to do basic lookups like this directly in the screen-wdiget using tags like
<entity-one> instead of creating a separate script and writing Java code. I'll leave it for you to
explore this.
Also, since there is a delegator object, can you just write to the database and do all your business
logic in .bsh scripts? The answer is yes, but for larger applications this is not considered good
practice. In fact, this is never done in any of the OFBiz applications.
Click to see the files created in this tutorial.

Summing Up
This should give you a basic idea on how to build web applications with OFBiz. There are many
more tools available to help you, and I will leave it to you to explore the existing OFBiz applications
to see what else you can do.
One tool that can be very helpful is the form widget, which allows you to generate standardized
forms automatically based on the fields from your data model or from your business logic services.
See this wiki page for more details.
Building a Complete Application with OFBiz
In this third tutorial, we will build a complete application with OFBiz. Our application will allow users
to sign in and create an entry about themselves, their various hobbies, and see other people who
have visited the site and their hobbies and comments as well. It is a simple guest book website.
Please be sure that you have read all the previous tutorials, as I will not repeat the same
information here.
Defining the Data Model
The first step is to define the data model. We want to track persons and their hobbies and lookup
all the hobbies of a person (or, alternatively, all the people who share a hobby.) The data model
thus calls for person, hobby, and person-hobby linkage.
With a relational database, you would define two tables, one for a person and one for a hobby, and
link them together with a third table. The third table would allow you to associate as many hobbies
as you would want with a person, and vice versa. You would define foreign-keys to constrain the
third table so only actual persons and hobbies are present.
OFBiz works similarly. You would define two entities, which we will call HelloPerson and HelloHobby,
and a linking entity, HelloPersonHobby, and establish a relationships between them. The
relationships serve as foreign-key constraints but also allow you to go from one entity to another
without having to remember yourself what their respective keys are (or change your code when
keys change.)
NOTE: We are creating an application with completely self-contained data model here for
illustration. If we were building a real application, the best practice would be to reuse as many
existing OFBiz entities as possible, so instead of creating our own HelloPerson, we would be using
the existing OFBiz Party/Person/PartyGroup entities.
To define data models, create an entitydef/ directory inside your application (hello3/ in this case)
and create an entitymodel.xml and entitygroup.xml inside your entitydef/ directory:
HelloPerson and HelloHobby each has a primary key, and HelloPersonHobby has two primary key
fields, which it uses to link HelloPerson and HelloHobby. It is considered good practice to give your
relations a foreign key name to make debugging easier and avoid accidental collision of foreign key
names OFBiz generates for you.
It is also very important (but easy to forget) to define these entities in another file, entitygroup.xml,
in the entitydef/ directory, so OFBiz will know which delegator, and thus database, to use for them):
Otherwise, the entities will exist in OFBiz, but when you actually try to use them, you will get this
error:
org.ofbiz.entity.GenericEntityException: Helper name not found for entity

HelloPerson
Finally, you must add this line to your ofbiz-component.xml to let OFBiz know to use this entity as
part of this application component, before the <webapp> directive:
<entity-resource type="model" reader-name="main" loader="main"

location="entitydef/entitymodel.xml"/>
<entity-resource type="group" reader-name="main" loader="main"
location="entitydef/entitygroup.xml"/>
Now start OFBiz. You will see the following lines in your console.log (Linux) or roll past you on your
console (Windows), telling you that your entities were loaded:

/home/sichen/eclipse/workspace/ofbiz/hot-deploy/hello3/entitydef/entitymo
del.xml
/home/sichen/eclipse/workspace/ofbiz/hot-deploy/hello3/entitydef/entitygr
oup.xml
When you go into webtools, you will see the entities:
Click on "All" to the right HelloPerson and you will see its fields:
Notice that next to each field is the Java type and SQL type for this field. The SQL type is specified
in the framework/entity/filedtype/ directory and varies depending on the database you are using
(mine is Derby.) If there were any values for this entity, it would show below the fields.
Creating Seed Data
Now let's create some seed data for our hobbies. In most OFBiz applications, we would create a
data/ directory inside our application and create an XML file for our seed data. Let's call ours
HobbiesData.xml:
This file, which is called an entity engine XML file, is a standard OFBiz XML format for importing and
exporting data. It is really quite simple. Use the name of the entity ("HelloHobby" in our case) for
the tag name, and use the name of the fields as either attributes or as inner tags (see the last value
for "WINE." The values for your fields can be the values of the attributes or inside the inner tags,
where they can be inside CDATA sections as well, in case you have very long values. Also, the key
fields do not have to be upper case or separated by _, but that is the norm in other OFBiz
applications.
Now you are ready to load your seed data. Go to the Web Tools application's "Main" screen, and
you will see links for "XML Import". Click on "XML Import" and on the next screen, it will prompt
you for the name of your file, relative to your ofbiz/ directory. I usually don't click on any of the
optional check boxes and just "Import". If you are successful, the same screen will come back and
tell you at the bottom how many values were added:
If your import failed, read the error message from your console.log file carefully. It is usually for
one of these reasons:
1. You used a value that was too long for a primary key. The OFbiz "id-ne" is a Java String, but
for SQL it is a 20-char VARCHAR.
2. You missed a required primary key field.
3. You tried to insert a field which would violate foreign key integrity.
If you read the log carefully you can identify which value (GenericValue) OFBiz was trying to create
and what the database error response was. It might also give you a somewhat cryptic foreign-key
name to chase down the offending foreign key violation.
You may have also noticed a "XML Export" links on the "Main" page of Web Tools. These links can
generate the entity XML files for you.
Now go to "Entity Maintenance" from the "Main" page, click on "All" next to HelloHobby, and you
will see the hobbies that were just inserted:
In addition to your fields and values, OFBiz also automatically creates timestamps of when your
values were created and updated, for synchronizing data across multiple instances of OFBiz.
Finally, OFBiz can automatically install your seed data during the install process if you add this line
to your ofbiz-component.xml file:
<entity-resource type="data" reader-name="seed" loader="main"

location="data/HobbiesData.xml"/>
OFbiz actually lets you define whether your data is "seed", which means they are required for your
app to run properly, and "demo", which means they are just for the demo.
Creating Business Logic
Now that we have the data model defined, we can of course write a simple application with a
delegator to access the entities directly. Standard practice for OFBiz applications, however, calls
for creating a separate layer for the business logic and for creating, updating, and removing entries.
The delegator is used directly for looking up values, although more complex lookups are also coded
as a service.
Creating services is a two step process. First, you define the service generically in an XML file,
which tells the OFBiz service engine what parameters your service takes and where to find it (class
and method or location of a script.) Then, you implement the service in Java, the OFBiz minilang,
or another scripting language.
Service definitions are usually inside a servicedef/ directory in your application and consists of one
or more services.xml files. Here is our services.xml file:
Notice how our services.xml references the entities they work with directly with the
<auto-attributes> tag, rather than specifying them outright. This saves you time and makes your
application easier to maintain.
You would also need to reference the service resource in your ofbiz-component.xml as well. In
addition, you must create <classpath> directives in ofbiz-component.xml to tell it where to load up
the apps. This is what our ofbiz-component file looks like, after adding the classpaths, entities
definitions, service definitions, and seed data:
Now it looks like ofbiz-component.xml for other OFBiz components, doesn't it?
Now to create the services. A Java service goes inside a src/ directory in your application and is
written in a standard fashion: A public class with public static methods which take two parameters,
a DispatchContext for getting objects like delegators, dispatchers, locale, and security, and a Map
called context which are your input parameters and returns a map of results:
Java services will also need to be compiled, with knowledge of the proper classpaths for other
OFBiz apps. This involves using ant and a build.xml build script, which you can usually copy over
from another application. It is a standard file in all OFBiz applications and framework components
and quite lengthy, so I won't include it here.
When you are done writing your service and creating the build.xml script, you can build your Java
services like this:
sichen@linux:~/eclipse/workspace/ofbiz/hot-deploy/hello3> ant
Buildfile: build.xml
init:
clean-lib:
[delete] Deleting directory
/home/sichen/eclipse/workspace/ofbiz/hot-deploy/hello3/build/lib
prepare:
[mkdir] Created dir:
/home/sichen/eclipse/workspace/ofbiz/hot-deploy/hello3/build/classes
[mkdir] Created dir:
/home/sichen/eclipse/workspace/ofbiz/hot-deploy/hello3/build/lib
classpath:
classes:
[javac] Compiling 1 source file to
/home/sichen/eclipse/workspace/ofbiz/hot-deploy/hello3/build/classes
jar:
[jar] Building jar:
/home/sichen/eclipse/workspace/ofbiz/hot-deploy/hello3/build/lib/ofbiz-pa
rty.jar
BUILD SUCCESSFUL
Total time: 2 seconds
The build process basically took all your files in the src/ directory, compiled them, and put them
into the build/lib directory.
Minilang is much simpler by comparison. The simple minilang service goes inside a script/ directory
and is an XML file with directives. Because it is designed especially for common OFBiz application
tasks, such as lookup data, store data, check premissions, and work with existing entities and
services, it can make those tasks very easy:
Finally, to test it, re-start OFBiz to load all the new definitions in ofbiz-component.xml and
services.xml. Then, open a beanshell window and test our service (Note: you should first download
bshcontainer.bsh and put it in your ofbiz/ directory):
Here, beanshell called the service dispatcher to run the service, and they were successful, so the
right values are created. (Ok, in reality it took about six tries, but I won't bore you with the details.)
So now you have created the data model and services for them. The next step is to put them into
the web application.
Creating the Web Application
Our web application will show a guest list of people who have visited the site and allow you to add
your name to this list. You can also click on a person and add a hobby for that person from a list of
available hobbies. We will build our application with the OFBiz screen-widgets and form-widgets to
show you how these tools can build web applications directly from the fields of your data model
entities and business logic services, without repetitive HTML code or Java code.
First, let us create two new screens in the screen-widget for our page of people and hobbies. Within
each page, there are two forms, one form showing the list of people or hobbies, the other for
adding another entry:
Notice here that I am not using a Freemarker page (.ftl) template but instead am calling a form
directly. Also, instead of using a .bsh script to look up data from entities, I am using directives such
as <entity-and> and <entity-one> in the <actions> part of the screen. Both tools were designed
to streamline the process of creating standard forms by reducing the need for display code (such
as FTL/HTML) or scripts to find data or call services.
The next step is to define the input elements using the OFBiz form-widget:
The form-widget allows you to define forms based on fields of an entity or parameters of a service,
and you can define forms which display a single entity or show a list of data or submit single or
multiple values to the controller. You can specify pull down menus and look up related entities, hide
fields, place hyperlinks, even calendar buttons and other widgets. Finally, forms can automatically
adjust when their related entity or service changes.
I will also take care of adding new requests and views to the controller and a link to the guest book
in the header. I've already shown how to do this in the previous tutorial and won't repeat it here.
What is different, though, is I need to add the requests to create person and add hobbies to the
controller:
These requests go directly to the services we've just defined. There is no need to create your own
event servlet method to parse form parameters--OFBiz will do that for you automatically.
Now our application is done. Here is the guestbook page:
and here is the hobbies page:

The look and feel for the site can be significantly improved with the use of stylesheets. All OFBiz
display tools, including Freemarker, form-widget, and screen-widget, support stylesheets.
Click to see the list of files for this application.
Maintaining your Application
Finally, a word about maintenance. After your code is written, you've actually just started. Studies
show that 50% or more of an application's lifetime costs is long-term maintenance, such as
handling user requests for changes or new features. With OFBiz, because the tools from user
interface to business logic to data model work together, such changes can be very easy.
For example, suppose that you need to add a new field, "middleName", to your entity for person.
All you have to do is add one line for it in your data model, like this:
OFBiz will do the rest for you. When you re-start OFBiz, you will see these lines roll across your
screen:
17149 (main) [ DatabaseUtil.java:277:WARN ] Entity "HelloPerson" has

9 fields but table "OFBIZ.HELLO_PERSON" has 8 columns.
17150 (main) [ DatabaseUtil.java:289:WARN ] Field "middleName" of
entity "HelloPerson" is missing its corresponding column "MIDDLE_NAME"
17151 (main) [ DatabaseUtil.java:1477:INFO ] [addColumn] sql=ALTER
TABLE OFBIZ.HELLO_PERSON ADD MIDDLE_NAME VARCHAR(20)
18013 (main) [ DatabaseUtil.java:302:INFO ] Added column "MIDDLE_NAME"
to table "OFBIZ.HELLO_PERSO
It already modified the database for you. Then, when you go to your application again, you will see
that the forms have all changed too:
When you submit your request, the service will run with the new field as well.
In other words, with one change in the data model, OFBiz has changed your database, your
business logic services, form handling in the controller, and your user interface forms. This is the
advantage of using the OFBiz tools for data modeling, business logic, and front-end design as a
package. Their mutually aware interactions will not only speed up your development cycle but also
significantly reduce your application's long-term maintenance costs.
Conclusions
Now you have built your first complete web application with OFBiz. You have seen first hand how
the data modeling, business logic, and user interface tools work together to create an efficient
framework for building and, perhaps more importantly, maintaining such applications.
Securing your OFBiz Applications
These are some general notes about how security in OFBiz applications works.
OFBiz can be secured at the user interface or business logic levels. At the user interface level, an
entire web application can be secured at once, individual requests in the controller can be secured,
and individual pages can require specific permissions. At the business logic level, each service can
require a specific permission.
Assigning Permissions
There is a SecurityPermission entity which describes granular security permissions, which could be
for a particular page or a particular service. SecurityPermission is a two part string, separated by
an "_". The first part specifies the application, the second part the operation allowed. Thus, you
could have a permission like "ORDERMGR_CREATE" which means that the user with this
permission can create information in the order manager. Some permissions end in _ADMIN, such
as ORDERMGR_ADMIN. Those permissions automatically have the right to every operation in the
application.
Individual security permissions are grouped together into groups with the
SecurityPermissionGroup entity which groups these permissions together. For example, you can
create a specific sest of permissions for customer service representatives who can view customer
information, enter orders, but not make purchase orders or access internal manufacturing,
accounting, or payroll information and functions.
Each SecurityPermissionGroup is associated with a UserLogin. A Party, which can be a Person or a

PartyGroup (ie, organization) can be associated with multiple UserLogins. Thus, a Person can have
some logins with more permission and some with less, which can be helpful with larger customers
(or larger families, for that matter.)
This can all be done in the Party Manager - Security tab.
Securing Web Applications
In the ofbiz-component.xml file where web applications are defined (with the <webapp> directive),
you can use the <base-tag> tag to specific required permission for the whole web application. Just
use the first part of the security permission string, which is the name of the application. For
example, if you put base-permission="ORDERMGR", the webapp will automatically require
ORDERMGR_VIEW or ORDERMGR_ADMIN.
In many applications, you will see base-permission="OFBTOOLS, ORDERMGR". What this means is
that OFBTOOLS_VIEW and ORDERMGR_VIEW are both required. The base-permission attribute
allows a series of permissions to be specified, and all of them must be true at the same time for the
user to gain access. The idea behind requiring both OFBTOOLS_ and ORDERMGR_VIEW is so that
a OFBTOOLS_VIEW controls the access to the web apps, while ORDERMGR_VIEW can be used to
control access to order information in any application, including the web-based Order Manager but
also the Point Of Sales store, the CRM module, or another application.
In the controller.xml file for the web application, you can specify security requirements for
individual requests with the <security> tag. You can use it for making the page secure with https
or requiring a user login (though not a user login with a particular permission) to view the page.
You can also hide the request altogether by making unavailable to direct requests from the browser.
This might be nice when you have a request which is part of a request chain that should not be
called individually.
Finally, on the pages themselves, you can use request that the page does not display unless the
user login had certain security permissions. OFBiz supples you with the UserLogin and a "security"
object (see Security API below) for checking these permissions in a .bsh file. If you are using
screen-widget, you can also use the following tags:
<condition>
<if-has-permission>
<check-permission>
<widgets>
<fail-widgets>
They allow you to check permission inside the widget directly without using FTL and then set up a
widget for when the permission is checked and a fail-widget when permission is denied.
Security API
The most popular security API methods are:
o Security.hasPermission - checks if the user has a particular permission

o Security.hasEntityPermission - will allow you to specify permission strings as two parts,
such as "ORDERMGR", "_CREATE", so if the user has "ORDERMGR_CREATE" or
"ORDERMGR_ADMIN" permission, it will pass.
o ServiceUtil.getPartyIdCheckSecurity - will check if the user has the specified permission or
is in fact performing the operation for himself (ie, userLogin.partyId == partyId). In either
case, will return the partyId, which means the user has permission.
o Security.hasRolePermission - will check if the user has the specified permission AND if the
user is associated with a particular entity in a role. The idea is if you give the user a
permission like ORDER_ROLE_VIEW and then specify that he is related to an order with the
OrderRole entity, then that user has permission to view that particular order. The same
user would not have permission to view orders for which he does not have an OrderRole
entity record.
The minilang simple methods also have permission checking tags <if-has-permission> and
<check-permission>.
You should also take a look at the full OFBIZ Security API for more information.
Securing Services
You can define whether a service requires a user login. In addition, you can use the <security> tag
to define what permissions are required. Inside the services itself, you can get OFBiz to check on
permissions for you. There is a security-related method which will check if the UserLogin has
certain permissions, or if the user is performing a task for himself (ie, creating an order for
himself.)
You can also define your permissions in the services.xml itself by using the
<required-permissions> and <check-permission> tags. See
applications/product/servicedef/services.xml, for example.
If you would like to work on a tutorial extending the "Hello World" applications to include some
security examples, please write on the mailing lists, and I will be happy to direct you on how to do
it.
Standardizing and Internationalizing OFBiz User Interfaces
It is a good practice to follow these instructions, even if you do not initially plan to internationalize
your application. They would help you keep your user interface labels in a standard .properties file,
so you make global changes, customization, and translation easier for you and your users later on.
Translating an Existing Application
It is fairly easy to translate OFBiz to other languages, and OFBiz has already been translated, at
least partially, to French, Italian, German, Spanish, Portuguese, and Chinese. Translating OFBiz
into another language just involves creating a new translation file.
Inside each OFBiz applications/ directory is a config/ directory where configuration properties and
language translation files are. For example, in the order manager application, you will find the
following files in the config/ directory:
sichen@linux:~/eclipse/workspace/ofbiz> ls -1 applications/order/config/
OrderErrorUiLabels_fr.properties
OrderErrorUiLabels.properties
OrderUiLabels_de.properties
OrderUiLabels_fr.properties
OrderUiLabels.properties
OrderUiLabels_pt_PT.properties
OrderUiLabels_zh.properties
taxware.properties
zipsales.properties
The files OrderUiLabels_xx.properties and OrderErrorUiLabels_xx.properties are the translations
of user interface (UI) labels to other languages. "xx" is the standard locale code of a specific
translation and comes from the getAvailableLocales() method of the Java Locale class, via an OFBiz
API called UtilMisc.availableLocales(). For example, "zh" means Chinese, "fr" means French, "de"
means German, "pt" means Portuguese.
Each UI labels translation file is a properties file of UI labels (usually in English) and their
translation into the language of the locale. So for example, here is what the French labels for the
OFBiz order manager looks like:
FacilityBillingAddressSameShipping = L'adresse de facturation est la

m\u00eame que celle de livraison
FacilityDeliveryOrder= Bon de livraison
FacilityFacility = Service
FacilityInventory = Inventaire
FacilityNoFacility = Aucun Service
FacilityNoOtherShippingMethods = Par d\u00e9faut : Aucun autre moyen de
livraison possible
FacilityShipAvailable = Livrer les produits d\u00e8s qu'ils sont disponibles
(peut occasionner des frais additionnels d'exp\u00e9dition)
FacilityShipOnceOrAvailable = Livraison compl\u00e8te ou partielle ?
FacilityShipmentDatas=Donn\u00e9es r\u00e9ception
FacilityShipments = Livraisons
FacilityShipping = Livraison
To translate OFBiz to a new language, create a new properties file for your locale.
Using UI Labels for Internationalization
If you are developing new screens, you will want to reference the UI label files so that you can
re-use them. In the OFBiz screen-widget, you can reference UI labels using the <property-map>
tag inside a screen's <actions> section. For example, the following code from the order manager's
"main-decorator" screen loads UI labels from different applications:
<screen name="main-decorator">
<section>
<actions>

<property-map resource="OrderUiLabels"
map-name="uiLabelMap" global="true"/>
<property-map resource="AccountingUiLabels"
<property-map resource="EcommerceUiLabels"
<property-map resource="ProductUiLabels"
<property-map resource="ManufacturingUiLabels"
<property-map resource="WorkEffortUiLabels"
<property-map resource="PartyUiLabels"
<property-map resource="CommonUiLabels"
Note that the typical pattern is to reference the needed UI labels in a main layout or decorator
screen and then reuse that screen throughout an application, so you would not need to reference
it over and over again for each screen.
Then, when you are actually writing your screens with freemarker templates (.FTL) or form-widget
XML files, use ${uiLabelMap.} instead of actual text. Later, you can define the translation of those
labels in the .properties files, as shown above.
Internationalizing data types
Subsequent to opentaps version 0.9, it is also possible to internationalize the data types stored in
the database, so "Purchase Orders" could become "Acquisto" in Italian. The following steps are
required:
o Create a series of translation files for each locale for your data labels, such as
OrderEntityLabels_it.properties for Italian and OrderEntityLabels.properties for the default
US English. Put these files in your config/ directory as above.
o In the entitymodel.xml, add the following to your <entity> definition:
o default-resource-name="OrderEntityLabels"
to point to your data labels file.
o When you display the order fields, use the .get(field, locale) method for the GenericEntity
or GenericValue, instead of .get(field), like this:
o ${orderType.get("description", locale)}
This can be done either in a form-widget or on an FTL freemarker template.
For an example of this, see SVN r 7557.

Internationalizing a New Application
To internationalize a new application, you would need to make sure that the config/ directory is
loaded for the application. This can be done by adding the following line to your
ofbiz-component.xml:
<classpath type="dir" location="config"/>
Contributing your Translations Back
By contributing your translations back to the open source project, you can help create a
community of other users in your country. Those users may, in turn, help implement features
which would help you, especially country- or region-specific features. You can also establish
yourself as an expert for your country or region, should other users require help.
To contribute your translations, create a JIRA issue for the OFBIZ applications or
a SourceForge.net issue for opentaps and upload a patch file of your .properties translations. A
patch file is created with
$ svn add file1 file2 file3

$ svn diff file1 file2 file3 > mychanges.patch
where file1, file2, file3 are the files you've changed. If you've created new files, the add step is
necessary. Otherwise, it can be skipped. For consistency, please make all your patch files
from the opentaps/ or ofbiz/ root directory.

Apache OFBiz Getting Started
http://docs.ofbiz.org/display/OFBADMIN/Apache+OFBiz
+Getting+Started
Added by David E. Jones, last edited by Jacques Le Roux on Jun 06, 2008
Apache OFBiz Getting Started
This document and it's related documents contain information about getting started with OFBiz.
After reading this document you might find these helpful as well as you get started on your journey into
the wonderful world of Apache OFBiz:
• The Demo and Test Setup Guide

• The Technical Production Setup Guide
• The Business Setup Guide
• OFBiz Source Repository and Access
• Framework Introduction Videos and Diagrams
• OFBiz Beginner's Development Guide Using Practice Application
• OFBiz Contributors Best Practices
The What, Why and How of Apache OFBiz
The basic structure and driving force behind OFBiz has a lot to do with the goals and actualization of the
release process.
OFBiz is and always has been a community-driven open source project. There is no central commercial
organization that drives the development of OFBiz or derives a project from the intellectual property of
the software or other project assets. This is formalized now that OFBiz is a project in the Apache
Software Foundation.
Because of this OFBiz always has been and always will be just what users who contribute to the project
want it to be. There are many different individuals and groups involved with many different needs and
our goal is to define and follow development and release policies that serve the needs of these parties.
So, let's start with that...
How Do I Decide What to Use?
From a project user perspective there is one main question that can help determine which way they will
want to get OFBiz: Do I want to contribute to the open source project?
For this question there are 3 main answers:
1. Yes, definitely: I want to contribute to design, coding, and testing efforts and thereby
collaborate with others to more effectively and efficiently satisfy the long-term requirements
from me, my clients, or my employer
2. Kind of: I want to stay on the cutting edge and participate with testing and feedback, but I'm
not in a position to participate in development and/or in the near future I will need something
more reliable and supported and that won't change very much
3. Not really: I'm happy to offer feedback, but I really need something that will work well now and
well into the future so we can get things going in our organization
For each answer there is a recommended way to get OFBiz:

1. Get the code straight from the code repository (SVN) trunk and update frequently through
development, stopping before your integration or final pre-deployment testing, and periodically
even after production deployment according to your ongoing develop/deploy plan; note that
when you are not updating from SVN you should continue to watch the commits for bug fixes to
patch into your code base
2. Get the code from the code repository (SVN) release branch and keep updated or patched
regularly as fixes are committed and the branch stabilizes over time; when getting started
choose the most recent branch, even if it is very new; when new release branches are created
update to them soon after the branch is done
3. Get a built release package or the code from a release branch tag, and update as new pre-built
release packages and tags are created; these will only represent fixes and unless a major issue
arises they will be backward compatible and generally safe to update or patch to; when getting
started choose a release branch that has been around for at least 2-3 months and that has no
major outstanding issues in the issue tracker to assure that it has stabilized; when new release
branches are created wait until you are ready to do a major upgrade and possibly need to modify
your code and configuration, and wait at least until the prospective branch has stabilized before
moving to it
Demo and Test Setup Guide
Introduction
This document describes an initial setup process and basic configuration options for the Open For
Business Project. For more detail see related documents such as the OFBiz Framework Configuration
Guide , the Entity Engine (database) Configuration Guide , the Service Engine Configuration Guide ,
and other related documents you may found at OFBiz Documentation Index
If you run into trouble there are various resources available to help. The first steps would be to search on
the New OFBiz Docs Site and Old OFBiz Wiki (now archived) , and then on the OFBiz Mailing Lists . If
you can't find you answer there, then subscribe to the Apache OFBiz Users Mailing List, and send a
message with as much detail as possible about the problem you are having.
Quick & Easy Setup
You can get up and running quickly by downloading the OFBiz Complete distribution and following some
simple instructions. For more options and explanations, see the rest of this document.
1. Download and install the Java 2 v1.5 series JDK/J2SDK (not the JRE, you need the full SDK)
from Sun's Java (J2SE) site, and make sure your JAVA_HOME environment variable is set to this
JDK after installation (NOTE that for Mac OS X no JVM setup is needed, just make sure Java is
up to date with the OS X Software Update facility)
2. Download the OFBiz release archive and unzip it in the directory of your choice (see comments
below about that, so for now checking out of SVN repository is preferred, see below...). This
should create one sub-directory: ofbiz. This will be the OFBIZ_HOME location.
3. Start OFBiz with embedded Tomcat by going into the ofbiz directory and then running
"startofbiz.bat" (or "%JAVA_HOME%\bin\java -jar ofbiz.jar") for Windows, or
"./startofbiz.sh"(or "$JAVA_HOME/bin/java -jar ofbiz.jar") for Linux/Unix. For OS X you can
just run "java -jar ofbiz.jar" and you don't need to setup the JAVA_HOME or anything because
it is already there.
4. Open a browser and go to http://127.0.0.1:8080/ecommerce/control/main for the
ecommerce application or https://127.0.0.1:8443/webtools/control/main for the WebTools
application or https://127.0.0.1:8443/catalog/control/main for the Catalog Manager
application.
5. The default administrative account is username: "admin", password: "ofbiz".
6. Have fun with it! You are running on a Java database. For more discussion of databases, read the
section below on that topic.
7. For more detailed options and configuration information, read on!
Building From SVN
When building from SVN you will need to have a Java 1.5 series J2SDK (NOT just the JRE, need to full
SDK) as mentioned above. The build is done using Ant, and sufficient Ant libraries are included with
OFBiz. If you have Ant installed separately just make sure you have version 1.5 or later, and then run Ant
as normal intead of as listed in the following examples.
In the directory where you want OFBiz to be, do a SVN checkout of the ofbiz trunk. For example:
svn co http://svn.apache.org/repos/asf/ofbiz/trunk ofbiz
For information on connecting to SVN click here.
Now go into the "ofbiz" directory and run "ant.bat" (Windows), or "./ant" (Linux/Unix/OSX). It will
compile all modules and leave you an executable jar (ofbiz.jar) in the "ofbiz" directory.
To load the seed and demo data, run "ant.bat run-install" or "%JAVA_HOME%\bin\java -jar
ofbiz.jar install" (Windows), or "./ant run-install" or*"$JAVA_HOME/bin/java -jar ofbiz.jar install"*
(Linux/Unix/OSX)
As an alternative to the previous step: to load the seed data only, run "ant.bat run-install-seed" or
"%JAVA_HOME%\bin\java -jar ofbiz.jar install -readers=seed" (Windows), or "./ant
run-install-seed" or*"$JAVA_HOME/bin/java -jar ofbiz.jar install -readers=seed"* (Linux/Unix/OSX)
To start the server run "ant.bat run" or "%JAVA_HOME%\bin\java -jar ofbiz.jar" (Windows), or
"./ant run" or "$JAVA_HOME/bin/java -jar ofbiz.jar" (Linux/Unix/OSX)
Another build option in the Ant build script that is useful is "ant.bat clean" (Windows) or "./ant clean"
(Linux/Unix/OSX). That will clean out all built classes allowing you to run "ant" again to get a clean build.
If you are running into funny errors after updating from SVN in the future, give this clean build process
a try first.
Database Setup
Database setup is done in the entityengine.xml file. There are many options there which are described
in the Entity Engine Configuration Guide
The OFBiz package comes with Derby, an open source Java database from IBM that complies with DB2
specs and is based on the Cloudscape product. This database is good for demonstration purposes
because it is easy to setup and use. It is not the best for large data sets and does not provide the same
performance or scalability that a major database would, but compared to HypersonicSQL (that we used
to use) it is significantly better because while not as fast for small scale operations it is closer to a
production database environment and allows us to catch issues earlier on. Smaller sites might even
consider this as an option for their production deployment, especially once the database is a bit more
stabilized.
There are many open source databases that will scale well and deliver good performance. The two most
popular are PostgreSQL and MySQL (4.1.11 or later, or the 5 series) . Postgres is a very full featured
database with transaction support, foreign keys, stored procedures, et cetera. Postgres also has very
friendly license terms. MySQL is a pretty good option these days as well. Please note that if you use this
in a commercial production instance you may have to purchase a commercial license because it is GPL
licensed and so is the JDBC driver. MySQL AB allows use of the JDBC driver in open source projects in
spite the GPL license, but this may not apply for commercial use of a modified OFBiz. For some a
commercial license is the preferred way to go anyway because of support and warranty and other issues.
For those with this preference considering Postgres there is also a commercial Postgres derivative called
EnterpriseDB.
Commercial databases are also supported. If you have database licenses for other needs, or have major
in-house familiarity with and support for a certain commercial database, then there is no reason not to
take advantage of that. OFBiz has been tested with Oracle, DB2, Sybase, MS SQL Server and others and
should work fine with any database that has a JDBC driver. Please note that we have experienced that in
some cases the JDBC drivers included with certain databases are not fully specification compliant. The
options are often to use the database-specific APIs or to get a third party driver. The database-specific
code is an issue because of licensing restrictions and additional difficulty needed to keep up with them,
so sometimes a third party (even a commercial one) is preferred. For example with Oracle we have had
much more success with the DataDirect JDBC driver.
There is no need to run any SQL scripts to create the tables or populate them with the default data. The
entity engine can create missing tables or fields when the server starts up and does so if the appropriate
property is set in the entityengine.xml file. This is the file that configures the servers for the entity
engine.
For the table creation routine to work properly, the field types must be set up. Do this by specifying the
corresponding fieldtypeXXX.xml (where XXX is the database name) file for the server in the
entityengine.xml file. These fieldtypeXXX.xml files are located in the
ofbiz/framework/entity/fieldtypedirectory.
Default data can be loaded through the "run-install" Ant target as mentioned in the Building from SVN
section.
J2EE Containers
OFBiz comes and runs by default with Tomcat for a Servlet/JSP container and the Geronimo Transaction
Manager for a transaction (JTA) manager. A patched version of Minerva (included in SVN) is the current
preference for a transaction aware connection pool, though as other options are made available that may
change.
OFBiz can also be configured to run in different containers, but there may be issues with certain quirks
that other containers have, especially with servlet containers. We have always been able to find
work-arounds for these, but they also seem to keep on appearing, so that is just something to watch for.
Because of the difficulty of deploying in an external application server we have created a configuration
and script template tool that takes the classpath and webapp settings from the various OFBiz files to
more easily generate the files you need. For more information, see the README file in the
ofbiz/framework/appservers directory. If you are looking for a good commercial J2EE app server, Orion
is a good place to start, but we recommend trying out Tomcat and Geronimo TM and see if they meet
your needs.
Apache OFBiz Technical Production Setup Guide
NOTE: this is the technical setup guide for OFBiz, for the business oriented one, look here.
Written by: David E. Jones With feedback and contributions from Ruth Hoffman, Andy Zeneski,
Si Chen, Chris Chesney, Hans Bakker, and Al Byers
Sponsored by:
Integral Business Solutions (http://www.go-integral.com )
Hotwax Media, Inc (http://www.hotwaxmedia.com )
1. Data To Gather for Setup

2. Technical Setup Process
1. Tools Installation
2. OFBiz Installation
3. Database Setup
4. Seed Data Loading
5. OFBiz Configuration
1. Cache Settings
2. Debug Settings
3. Security Settings
4. URL and Port Settings
5. Ports, Default Values
6. SSL Certificate Setup
7. Currency, Locale Settings
8. Email Server Settings
9. Mounting a Root WebApp
6. Running OFBiz
7. Running OFBiz Automated Tests
8. Performance Monitoring and Tuning
3. POS Setup Process
Data To Gather for Setup
1. Technical Info
1. Host/domain name to deploy on (and ports if not 80, 443)
2. Web server setup: direct to Tomcat/Jetty, through Apache, using another (stand-alone)
application server?
3. Which database to use. Is the database installed on a remote server or installed
locally ?
Technical Setup Process
Tools Installation
1. Check/install Java SDK (need 1.5 series full SDK, not just JRE)
2. Check/install SVN client
Expert Recommendation: If you intend to only install a binary release version of OFBiz you will not need
the SVN client.
3. Check/install ant (1.6 or later)
OFBiz Installation
1) If you intend to use a development version of OFBiz, follow the instructions on the Source Repository
Info page to checkout the latest code or your desired stable branch
2) Build using "ant" in the ofbiz home directory (the directory where you installed OFBiz)
Database Setup
By default OFBiz includes and is configured for an embedded Java database called Derby. This database
used to be called Cloudscape but was purchased by IBM, changed to be DB2 specification compliant, and
then release as open source. This is a great database for demonstration, testing, development, and even
small-scale production environments.
Expert Recommendation: We generally do not recommend the Derby database for production because it
is not as easy to administer and optimize and will generally not perform as well as more substantial or
native databases as Derby is a lighter weight Java database.
Expert Recommendation: There are many databases that OFBiz can use, both commercial and open
source. While there are significant production instances of OFBiz running against Oracle, MS SQLServer,
and so on, we generally recommend using an open source database such as Postgres or MySQL. The
database to use is an important decision and may affect many things down the road. If you do not have
a preferred database to use, we recommend discussing options with an experienced consultant before
making a final decision.
1. If you decide not to use the embedded Derby database, check/install your database of choice
2. If necessary, put the correct JDBC driver in:
1. ${ofbiz install dir}/framework/entity/lib/jdbc
2. replacing the old or incorrect version of the driver there (ie copy in with same name to
avoid problems with update restoring the old driver later)
3. To setup the Entity Engine to use a different database from the default Derby database.
In the: ${ofbiz install dir}/framework/entity/config/entityengine.xml file:
Modify an existing datasource (near the bottom of the file) or create a new one by copying one of the
sample datasources already there and giving it a new unique name
1. If using the default OFBiz transaction manager and connection pool, update the data URI,
username and password in the inline-jdbc tag
2. If you want your OFBiz tables in a special schema first create that schema in your database, then
set the schema-name attribute on the datasource tag
3. Find the "default" delegator near the top of the file and change the datasource-name attribute
value in the group-map tag under it to the name of the data source you modified or created.
Expert Recommendation: if you are using an external app server or want to setup more advanced Entity
Engine configurations, see the Entity Engine Configuration Guide or other online documentation.
The training videos from Undersun Consulting are highly recommend if you get into more advanced
usage of OFBiz.
Initial Data Loading
To load the initial data just use the OFBiz install routine through ant or directly with Java and the ofbiz.jar
executable JAR file. By default the install routine will load the "seed" and "demo" sets of data files, as
defined in the entityengine.xml file and in the ofbiz-component.xml file in each component. Run one of
these two options from the command line in the ofbiz home directory to run the default install routine:
ofbiz$ ant run-install
or
ofbiz$ java -jar ofbiz.jar -install
help can be obtained by by the following commands:
ofbiz$ java -jar ofbiz.jar -help
or
ofbiz$ java -jar ofbiz.jar -install -help
Note that you can choose to only load the basic "seed" data and not load the "demo" set of data files. To
do this run something like:
ofbiz$ java -jar ofbiz.jar -install -readers=seed,seed-initial
Definition: Seed Data is data that an application requires in order to run. It is created and maintained
along with the code and should be loaded into the database when the code is updated. It should not be
changed or removed in the application database without first having done so in the Seed Data XML files.
In OFBiz these are the source of the Seed Data and they are maintained in the code repository along with
the code. Add in components should do the same for this sort of data.
Definition: Seed Initial Data is data that is only required the first time the system is loaded like the
password of the admin user. Later if you want to update the seed data, you normally do not want the
password of admin set back to the 'ofbiz' value.
Expert Recommendation: For smaller installations we recommend loading the demo data and modifying
it through the OFBiz applications rather than creating all of the data from scratch.
For larger installations we recommend creating data files with your own settings, copied from the demo
data, or simply creating all data from scratch. These can be added to the "ext" set of install data files,
which is done by referencing those files in an ofbiz-component.xml file entity-resource tag with the
attribute reader-name="ext". To load the "seed" and "ext" groups run something like:
ofbiz$ java -jar ofbiz.jar -install -readers=seed,ext
or the special ant target:
ofbiz$ ant run-install-extseed
The OFBiz demo data includes a Party with ID "admin" and it has a number of UserLogin accounts
associated with it that have varying permissions. Note the following configuration changes:
1. For production systems the passwords on all UserLogin accounts associated with the "admin" party
should be changed from their default values.
2. The default password for the "admin" userLoginId is "ofbiz", as it is for the "flexadmin" and
"demoadmin" accounts.
The "1" account is meant to be used with the POS system so the new password should include only
numbers to make it easier to use with the POS client.
Expert Recommendation: while the "admin" party is the most critical to make sure the passwords are
changed for, there are other parties you should check, and change the password for all User Login
accounts associated with these parties. This includes "ltdadmin" and "externaluser" and if the demo data
is loaded (done by default) then also the users "DemoBuyer", "DemoRepAll", and "DemoRepStore".
OFBiz Configuration
Cache Settings
${ofbiz insall dir}/framework/base/config/cache.properties
Fresh from SVN, this file is configured to be development friendly to reload resources frequently. For
production use the expire times for the caches in the last section of the file should all be commented out
by putting a pound sign "#" at the beginning of each line. The properties in question start with
"minilang.", "script.", "webapp.", "widget." And "template.".
Debug Settings
${ofbiz install dir}/framework/base/config/debug.properties
This file is used to enable/disable different logging levels and used to configure Log4J logging level and
output settings. For most production use it can stay as-is. Disabling the "info" and "timing" level
properties can save some resources on the server, but we recommend leaving all of the others enabled.
To do this just change the values of the "print.info" and "print.timing" properties to anything except
"true".
Security Settings
${ofbiz install dir}/framework/security/config/security.properties
There are various settings you might want to configure in this file, but for most production use it can
remain unchanged.
If you want to use LDAP for user authentication:
• Set the security.ldap.enable property to true.

• Using the ${ofbiz install dir}/framework/security/config/jndiLdap.properties file:
o Change the java.naming.provider.url property to point to your LDAP server.
o Change the ldap.dn.template to use the Distinguished Name appropriate for your LDAP
installation.
If your LDAP installation is simple (all of your users are in a single organization unit) then these are all
the changes needed. If your users are in more than one organizational unit, then you will need to set up
each user's distinguished name using the Party Manager View Profile -> Update UserLogin Security
Settings screen.
By default, OFBiz will authenticate the user to LDAP first, and if successful it will synchronize the user's
OFBiz password to the user's LDAP password, and then proceed to authenticate the user to OFBiz (using
OFBiz's internal permissions logic). If LDAP authentication is unsuccessful, the user is still authenticated
to OFBiz. This is the behavior appropriate for most installations.
If you want the entire authentication process to fail if LDAP authentication fails, then set the
security.ldap.fail.login property in ${ofbiz install dir}/framework/security/config/security.properties to
true. Only users who are in the LDAP directory will be able to use OFBiz. This would be appropriate for
installations that use only the back office (manager) applications.
URL and Port Settings
The following configuration files contain port configuration that may configured for custom OFBiz
installations:
• ${ofbiz install dir}/framework/base/config/ofbiz-containers.xml (The Containers Configuration

File)
o Sometimes other container configuration files are used, but are generally in that same
directory and will be specified in the start properties file used (see start.properties,
pos.properties, install.properties, etc)
o The integration with Shark in OFBiz is still not complete, so we recommend disabling
Shark. So, the Shark container configuration near the beginning of the file should be
commented out.
o The BSH client (the last container in the file) should generally be disabled or at least
protected by a firewall for production deployments. Otherwise this is a significant
security risk.
o Note that if an external application server is used instead of the embedded Tomcat or
Jetty servers then many things normally configured here will be configured in the setup
files for the external application server.
• ${ofbiz install dir}/framework/webapp/config/url.properties (The URL Properties File)

o These properties are used to configure the settings to send to the client browser. The
port and host settings may be different than the port and host settings of the local
machine if it is running through Apache through AJP, through any proxy, or through a
load balancer of any sort. The settings in this file should be set to what the client
browser will see when communicating with your system.
o Note that the settings in this file can be overridden on the WebSite record with the ID
specified by the webSiteId field in the web.xml file in each webapp, if applicable. These
can be viewed and modified in the WebSites tab of the Content Manager application.
• ${ofbiz install dir}/framework/base/config/jndiservers.xml (JNDI Servers XML File)

o Generally only the "default" server is used which has automatic configuration through
the Java standard JNDI facility, so no changes are needed for most production
deployments in this file.
• ${ofbiz install dir}/framework/base/config/jndi.properties (JNDI Properties file)

o This is a standard Java JNDI configuration properties file and is used to configure the
local JNDI server to be used. Note that this is how the "default" JNDI server in the JNDI
Servers XML File is configured. If this file is not present the Java standard JNDI classes
will use various defaults instead.
• ${ofbiz install dir}/framework/service/config/serviceengine.xml (Service Engine XML file)

o Most of the settings in this file can remain unchanged for production deployments, but
there are some default server locations that refer to port 1099 (JRMP, for RMI) and
8080 (HTTP). These are in the "service-location" tags in the file.
• ${ofbiz install dir}/framework/jotm/config/iiop.properties (or jrmp.properties) (Carol IIOP or

JRMP Only Properities)
o The default transaction manager in OFBiz is called JOTM and it includes a remote
communication container called Carol that implements various standard protocols.
o There are two configuration files here as examples of two different ways of configuring
Carol in JOTM. The iiop.properties file sets up the IIOP and the JRMP protocols, while
the jrmp.properties file only sets up the JRMP protocols. The properties file to use for
Carol in JOTM is specified in the ofbiz-containers.xml file, or whichever containers XML
file you are using, in the "jndi-config" property of the "jotm-container" container.
o The only part of OFBiz that uses the IIOP protocol is that Shark workflow engine. The
integration with Shark in OFBiz is still not complete, so we recommend disabling Shark
and turning off IIOP. To do this change the jndi-config property in the jotm-container
container in the ofbiz-containers.xml (or other containers XML) file from iiop.properties
to jrmp.properties.
• ${ofbiz install dir}/framework/webapp/config/fop.xconf (FOP configuration file)

o the default settings in this file can remain unchanged for production deployments, but
you may need to change the "base" element (the default value is
"http://localhost:8080") to point to the modified base url (it is used by FOP to resolve
relative paths, e.g. to images) .
Widgets setting
${ofbiz install dir}/framework/widget/config/widget.properties
• To ease development (Out Of The Box, OFBiz is configured in development mode) the
compressHTML properties in general.properties if OFF. If you prefer to strip unnecessary
whitespace from HTML output you can set it on ON (uncomment the line
"#compress.HTML=true"). Note that, it is NOT the same thing as gzipped HTTP 1.1
compression.
• For the same reason (development mode) the line "widget.verbose=true" is uncommented. If
you do not want to see any informations about widget boundaries in the generated HTLM code,
you should comment this line.
Ports, Default Values
• HTTP - 8080
o Configured in: Containers XML File
o Referenced in: Service Engine XML File, Client Browser (if running direct), URL
Properties File
• HTTPS - 8443
o Referenced in: Client Browser (if running direct)
• AJP13 - 8009
o Referenced in: Apache mod_jk plugin configuration
• JRMP (JNDI, RMI, etc) - 1099
o Configured in: Carol Properties (carol.jrmp.url)
o Referenced in: Containers XML File, JNDI Properties File, Service Engine XML File
• IIOP (Shark, etc) - 2000
o Configured in: Carol Properties (carol.iiop.url)
o Referenced in: Containers XML File
• BSH Client - 9989, 9990 (this should generally be disabled or at least protected by a firewall)
SSL Certificate Setup
Choose a password to enter later when prompted. This same password will be used for the keystore
password and for another question a bit later as the key password for.
1. Run: "keytool -genkey -keyalg RSA -alias ssl -keystore [keystore name]"
Go through and answer the following questions:
Enter keystore password: [password]
What is your first and last name?

[Unknown]: www.mydomain.com (example)
What is the name of your organizational unit?

[Unknown]: Undersun Testing (example)
What is the name of your organization?

[Unknown]: Undersun Testing (example)
What is the name of your City or Locality?

[Unknown]: New York (example)
What is the name of your State or Province?

[Unknown]: New York (example)
What is the two-letter country code for this unit?

[Unknown]: US (example)
Is CN=www.mydomain.com, OU=Undersun Testing, O=Undersun Testing, L=New York, ST=New York,

C=US correct?
[no]: yes
Enter key password for

(RETURN if same as keystore password): [password]
2. Run: "keytool -certreq -alias ssl -keyalg RSA -file certreq.csr -keystore [keystore name]"
The following will be prompted/shown:

Enter keystore password: [password]
The CSR will be saved in the current directory: BEGIN NEW CERTIFICATE REQUEST and END NEW
CERTIFICATE REQUEST
3. Submit the CSR to a signing authority (Thawte, Verisign, etc)
4. Download your certificate from the signing authority. Please remember to download the Certificate in
PKCS#7 format
5. Import the Certificate into the keystore by running:

"keytool -import -alias ssl -trustcacerts -file mysignedcert.cer -keystore [keystore name]"
6. Configure the ofbiz-containers.xml file to point to your new keystore and password:
• If using Tomcat (Catalina), which is the default, find the "catalina-container" ->
"https-connector" -> "keystore" and "password" properties and set them.
• If using Jetty find the "jetty-container" -> "https-listener" -> "keystore" and "password"
properties and set them.
• For other Servlet containers, see the documentation for that container to find out how to set the
HTTPS keystore and password settings.
Currency, Locale Settings
Currency settings may be configured in the following configuration file:
${ofbiz install dir}/framework/common/config/general.properties
• Default Currency Code (must exist in Uom table, three letter code, see seed data in the
CurrencyData.xml file): currency.uom.id.default=USD
• Default Country Code (must exist in Geo table, is three letter ISO country code, see seed data
in the GeoData.xml file): country.geo.id.default=USA
• Default Time Zone: timeZone.default
• Note that these settings can be overridden for a Store in the Edit Product Store page.
You can constrain the available locale using locales.available.

For instance
# -- locales made available separated by comma's
locales.available=en,fr,de,it,nl,es,ja,zh
Email Server Settings
e-mail settings may be configured in the following, OFBiz file:
${ofbiz install dir}/framework/common/config/general.properties
• SMTP Server (relay host): mail.smtp.relay.host

• SMTP Username (if needed): mail.smtp.auth.user
• SMTP Password (if needed): mail.smtp.auth.password
• Turn on email notifications by setting the mail.notifications.enabled property to "Y".
If you are having trouble getting OFBiz to connect to your mail server, try disabling your anti-virus
software (temporarily) as it may block attempts to send emails from unknown apps because it thinks
they are being sent by a virus.
Mounting a Root WebApp
It is often desirable to have one of the webapps mounted on the root. This is often either the ecommerce
webapp or your own web site, which is created as a webapp in an OFBiz component would be setup the
same way.
1. To set the mount point to root (or "/") for a webapp, find the corresponding "webapp" tag in the
appropriate ofbiz-component.xml file and change the "mount-point" attribute on that tag to
equal "/".
2. For the default OFBiz ecommerce webapp, this is found in the file:
${ofbiz install dir}/applications/ecommerce/ofbiz-component.xml
Running OFBiz
There are various ways to run OFBiz, and they all come down to some variation of the executing the
"ofbiz.jar" executable JAR file. On the command line this can be as simple as:
ofbiz$ java -jar ofbiz.jar
or through ant:
ofbiz$ ant run
Then to access the application from your browser follow advices in Demo and Test Setup Guide
For production use you will want to setup a start script that contains special settings for things like
memory heap size, and so on. There are example start and stop scripts in the root ofbiz directory in the
startofbiz.sh and stopofbiz.sh files.
Expert Recommendation: Instead of running the startup and shutdown scripts manually it might be a
good idea to set them up as services on the system, or use something like daemontools to make sure the
process is restarted automatically if it goes down for some reason.
Running OFBiz Automated Tests
Each component running in OFBiz can have its own set of tests. These are usually defined in the "testdef"
directory in each component, and the test set XML files are specified in the ofbiz-component.xml file for
each component.
To run all automated tests use the following command:

ofbiz$ java -jar ofbiz.jar -test
To run just the tests for one component run something like (for the entity component):
ofbiz$ java -jar ofbiz.jar -test -component=entity
Performance Monitoring and Tuning
Expert Recommendation: While some steps can be taken at this point in the configuration process, the
real performance testing and tuning should be done after you have setup your catalog, categories and
products, and after you have customized any templates you plan to.
As mentioned above a critical part of performance tuning is turning off the expire times in the
cache.properties by commenting out the lines near the bottom of that file that set those values.
General Cache Information
You can get a lot of good information on database and configuration file (XML, properties, etc)
performance by looking at the statistics in the cache management page in Web Tools. They are all listed
there with statistics about hits and misses, and about why cache misses happened.
There are three causes for cache misses:
1. Not Found
2. Soft Reference clearing (is done during garbage collection)
3. Expire Time reached for an entry in the cache
Memory Settings
If you are running into problems with Soft References (as seen on the cache management page in
WebTools), the case is generally that your heap memory settings are less than ideal. Every time Java
does a memory allocation and finds it needs to grow the heap size it first does a garbage collection and
clears out soft references. The Entity Engine caches all use Soft References to avoid overrunning
memory with cached database data.
In other words, you may have 2Gb of memory on the box, but you are probably only starting with 64Mb
(or even less) and have a max heap of 128Mb. These are done with the following java command line
arguments: -Xms64M for the low size, and -Xmx128M for the max size. We usually recommend a max
heap size of around 75% of the memory on the box, but that depends on the operating system of
course... The small size should be pretty high, perhaps even as high as the max, to avoid the caches
being cannibalized during allocations and garbage collections as described above.
Database Intensive Operations
The comments above on memory settings, caches, etc. are for category browsing pages and such where
just about everything should be cached. For db intensive operations, like the product searching, it's
much better to focus on how the db is doing with the queries.
POS Setup Process
The Point-Of-Sale (POS) component in OFBiz is still maturing, but is already a very flexible and capable
enterprise class POS solution that features:
• templated receipts
• XML file configurable screens
• jPOS hardware support
• multi-tiered synchronization of product, price, promotion, party, order, and other data related to
POS deployment and operation
The POS system is designed to run with its own database in a totally stand-alone mode. This was done
so that even if the machine is totally cutoff from the network it can still operate.
To run OFBiz in the POS "mode" just run:
java -jar ofbiz.jar -pos
Note that this uses the pos-containers.xml file instead of the ofbiz-containers.xml file and by default it
doesn't load a web container (Tomcat by default), but it can be changed by adding the catalina-container
block. This allows to run the POS conccurently with Web eCommerce and Back Office.
The Store for the POS needs slightly different settings than for a web store. There is an example POS
Store in the demo data. One of the differences to note is that the POS Store should always have the Is
Immediately Fulfilled field set to Y, whereas for an online store or other mail or phone or store it should
be set to N. The POS Store should also have Manual Auth Is Capture set to Y, and typically Check
Inventory and Require Inventory should be set to N.
There are many files under the specialpurpose/pos directory that you may want to customize as you set
it up.
The receipt templates are .txt files in the config directory there.
The screens are configured through XUI in various files under the screens/default directory.
Button events are configured in the config/buttonevents.xml file.
The POS is translatable, see the config directory.
There are example synchronization settings in the data/PosSyncSettings.xml file, which is just an Entity
Engine seed data file that gets loaded into the database. This example is for 3 tiers: a Main Central
Server (MCS), a Per-Store Server (PSS) and the Point-Of-Sale client (POS). There are example sync
settings to do 4 data moves including MCS -> PSS, PSS -> POS, POS -> PSS, and PSS -> MCS. This uses
the Entity Synchronization service in the Entity Engine and the XML import file for this has pretty good
comments about what does what. Note that the services shown in the example are configured to use the
location "entity-sync-rmi" which is a pre-defined location specified in the serviceengine.xml file. Note
that to help avoid duplication of sequenced IDs in the data that is synchronized up the chain from the
POS terminals a unique prefix should be setup for the Entity Engine using the sequenced-id-prefix
attribute of the delegator element in the entityengine.xml file.
Note that OOTB the login/pwd are 1/1 (or 2/2 for a non manager person) and you must open the register
before being able to play with the POS. To open the register click on the MGR button on the top and near
the right, and then on the "Open" button on the right side of the screen near the top.
IF you need to do some JavaPOS settings you may find this page
interesting http://docs.ofbiz.org/x/0AM
Apache OFBiz Business Setup Guide
With an Emphasis on eCommerce
NOTE: this is the business setup guide for OFBiz, for the technical oriented one, look here.
Written by: David E. Jones With feedback and contributions from Ruth Hoffman, Andy Zeneski,
Si Chen, Chris Chesney, Hans Bakker, and Al Byers
Sponsored by:
Integral Business Solutions (http://www.go-integral.com )
Hotwax Media, Inc (http://www.hotwaxmedia.com )
Table of Contents
1. Purpose and Goal of This Document

2. Data To Gather for Setup
3. General Terms and Information
1. OFBiz "Manager" Applications
2. Other OFBiz Terms
4. Business Setup Process
1. General Company Setup
1. Company Contact Information
2. Facility (Warehouse) Setup
3. WebSite Setup
4. Store Setup
1. Store Settings
2. Store Role Settings
3. Promotional Settings
4. Catalog Settings
5. Web Site Settings
6. Sales Tax Settings
7. Store Shipping Settings
1. UPS Online Rate Estimates
2. UPS XPCI Integration
3. USPS Online Rate Estimates
8. Store Payment Settings
1. Payment Processor Details
2. PayPal Payment Setup
3. CyberSource Payment Setup
4. Giftcards
9. e-mail Settings
10. Survey Settings
11. General Settings Override
5. Catalog, Category, Product Setup
1. Catalog Setup
2. Category Setup
3. Product Setup
1. Add Content to the New Product
2. Add Prices to the Product
Purpose and Goal of This Document
In addition to being an excellent development framework and platform for enterprise information
automation, OFBiz also features many great applications that can be used out of the box without a lot of
customization. However, since it is enterprise class software, there are a lot of configuration options,
settings, and data structures that require some level of familiarity.
The purpose of this document is to help you get OFBiz setup for production use, with an emphasis on
eCommerce deployments. This is not meant to be a complete discussion of issues or decisions to make
or options to configure, just an overview of the basic settings that need to be configured for a production
instance of OFBiz.
This document is meant to be a series of instructions to be followed in order, except where a part of the
document says otherwise (there are very few). Of course, if you feel comfortable with the topics
discussed here you can use it as a reference and not follow it as a list of instructions.
NOTE: We recommend that you read this entire document before starting the process or making any
changes. While you are reading it is helpful to look at the files and web pages in question so you can
visualize better where things go and what they look like. Naturally you can ignore this, but a half hour
studying this document could save you a lot of time late
Note on Typographic Conventions Used in This Document
Text enclosed in a square box such as [[ ]] represents an OFBiz application browser tab selection.
Throughout the document the author has provided expert advice or other observations. These notations
are indicated as follows:
Expert Recommendations: Here is some text you better pay attention to!
A notation used throughout this document to indicate the starting directory (or root) location for the
OFBiz installation is \${ofbiz install dir}. This is typically followed by the path name location of the file or
directory being discussed.
Where OFBiz application manager web tools have individual page name or table name titles, the page
names and titles are highlighted with a background color: This Is A Page
Data To Gather for Setup
1. Company Party (Party Manager -> Find -> Profile; partyId: Company)
1. Name
2. Customer Service
1. Telephone Number
2. Email Address
3. Correspondence Postal Address
2. Warehouse Facilities (Facility Manager -> Facilities -> Facility)
1. Title for each (ie Web Store Warehouse, or California Warehouse, or Burbank
Distribution Center)
2. Telephone Number
3. Shipping & Receiving Postal Addresses (with names)
3. Email Settings (general.properties)
1. SMTP Server (relay host)
2. SMTP Username (if needed)
3. SMTP Password (if needed)
General Terms and Information
OFBiz "Manager" Applications
OFBiz provides a number of Manager applications, which make up the "back office" functions of the suite.
These applications are not intended to be customer or public facing, but rather tools to be used to
administer and manage the OFBiz software. Manager applications are, by default, accessible using
standard URL addressing and built-in OFBiz security services.
Manager applications which will be referenced in this document include the:
"Catalog Manager" accessed at:
http://localhost:8080/catalog/control/main
"Party Manager" accessed at:
http://localhost:8080/partymgr/control/main
More technical web based tools, or tools for the OFBiz framework are available in the "Web Tools"
application: http://localhost:8080/webtools/control/main
Note: OFBiz will automatically make adjustments between non-secure and secure pages based on login
requirements. Therefore, you can use the http (non-secure) notation to access the above mentioned
manager applications when first attempting to access them.
Once you are logged in to any of the OFBiz Manager Applications, tabs across the top will be in place to
allow you to easily switch from one application to another, or to open them in a separate window or
browser tab.
Other OFBiz Terms
In OFBiz a "Party" refers to a single entity such as a human being or a company or a family or even a
group of friends. In other words, it can represent an individual (a Person) or a group of parties, including
individuals and other groups (a Party Group).
The "Entity Engine" refers to the embedded OFBiz database access engine. Likewise there are other
"engines" in OFBiz including the Service Engine which is another critical tool that is the foundation of the
service oriented architecture for logic and processes in OFBiz.
Business Setup Process
General Company Setup
There is a Party with the ID "Company" that is configured as the default Party that represents the
company that owns or is running the system. You can have multiple organizations configured in the
system, but this one is referred to be default in the Demo Product Store (which we will be modifying and
not replacing in a minute).
Company Contact Information
In the Party Manager "Find" page type in "Company" in the Party ID field and press enter. This will bring
up the View Profile page for the Party.
On this screen change the existing address which represents the "Billing (AP) Address", "Payment (AR)
Address", and "General Correspondence Address". Note that if desired you can remove purpose(s) from
this address and create other addresses for those purposes.
You should also setup any telephone numbers and email addresses you want for your Company.
Facility (Warehouse) Setup
There is a Facility with the ID "WebStoreWarehouse" that we will be modifying in this step. This is the
default fulfillment facility for the Demo Store (which we will be modifying and not replacing soon). You
can create other Facilities here, but for this basic setup we will keep the single warehouse configuration
and modify this warehouse in place.
In the Facilities List in the Facility Manager click on the "Web Store Warehouse" link, and for that facility
click on the "ContactMechs" tab/button.
There is already an address setup that is a Shipping Destination Address and a Shipping Origin Address.
To setup your Facility's address just "Update" this address.
There is already a phone number setup that is a Shipping Destination Phone Number and a Shipping
Origin Phone Number. To setup your Facility's phone number just "Update" this phone number.
There are various other things that can be setup here including more advanced options such as Facility
Locations for inventory, and so on. This is also where you can go to manage picking/packing and shipping
of orders, and the receiving of returns, purchase orders, and so on.
WebSite Setup
There is a WebSite already setup with the ID "WebStore". This ID is referred to in the webSiteId field of
the web.xml file in the eCommerce webapp.
For this basic setup we will leave this as is. If you create a custom webapp for your ecommerce site, be
sure to set the appropriate webSiteId in the web.xml file.
The WebSite record is used to configure which Product Store to use for the ecommerce site that
references it. This WebSite is already configured to refer to the "OFBiz E-Commerce Store", which we will
be modifying, so there is no need to change anything here.
Note that the settings in the url.properties file can be overridden for each WebSite, as can be seen on the
Edit Web Site page in the Content Manager.
Store Setup
There is a demo eCommerce store already setup with most of the options we need, so instead of creating
a new one we will use that one and just change it's name and other options. The ID, which is 9000, will
stay the same.
To modify this store go to the Catalog Manager application and select the Stores top level tab. This will
bring up a Product Store List. Select the store with ID 9000, which by default has the name "OFBiz
E-Commerce Store".
As we setup the store we will cover each tab in order and discuss options on that page and related
options in configuration files:
Store Settings
Change the Store Name to something more applicable. This is mostly for internally referring to your
store and won't be shown to the customer.
Change the Company Name to something more applicable, as desired.

There are various settings that can be used to change the way things show up in the default OFBiz
eCommerce templates. You can change these for options you prefer, or for most fields you can empty
them to have nothing displayed there.
The Title and Subtitle show in the header.
The Style Sheet refers to a CSS style sheet to use for the colors, fonts, etc for the site.
The Header Logo, Header Middle Background, and Header Right Background specify images in the 3
main areas of the header. To show no images, or background images, leave these blank.
The Pay To Party Id field is already set to Company as it should be, and that is the Party we configured
earlier. For multiple organizations or if you have another company Party setup the party ID can be
specified here.
To remove the demo messages on the checkout screens and order emails change the Is Demo Store field
from Y to N.
The Inventory Facility Id and the various inventory settings are already setup with good default, but you
may review and change them as desired. Typically the only one you may want to change is the Require
Inventory field. By default it is set to N, but changing it to Y will cause products to only be purchasable
if they are in stock.
There are many other settings on the Store, most of which you won't want to touch. For more
information on them see the Undersun documentation site or other such reference material
Store Role Settings
There are various reasons why you might want to associate a Party with a Store. The main one to
consider is in order for a Party to take sales orders for a specific Store the Party must be associated with
the Store in the "Sales Representative" role.
Promotional Settings
This is where you can associate promotions (setup in the Promos header tab) with the store, including
effective dating, sequencing and so forth.
There are all example promotions and it is good to keep them in the database for future reference, but
you can delete all of these store associations so they won't get in the way for this store. Just click on the
"[Delete]" link for each one.
Catalog Settings
This tab shows all Product Catalogs associated with this Store. The demo data has two Catalogs
associated by default, and you can remove both of them since we will be creating a new Catalog later.
These two you can leave in the database as examples for future reference, but click on the "[Delete]"
buttons here to remove the associations with the Store.
Web Site Settings
This tab shows all WebSites associated with this store, or that this store is associated with. You will see
that the demo data already has this Store associated with the eCommerce Web Site, and the Order Entry
Web Site.
Leave these defaults as they are.
If you have your own ecommerce webapp and have created a WebSite for it as described above,
associate that WebSite with the store.
Sales Tax Settings
It is possible to use other tax calculation services or integrate with other tax calculation software, and
there are others included with OFBiz, but the default one uses a simple OFBiz entity with records for
different tax jurisdictions and effective dates.
The demo data includes one example that applies for any Country, State, and Tax Category, has no
Minimum Purchase amount, and the tax rate is 10%. Note that the tax rate is entered as a decimal
number and not a whole percentage number. In other words, 10% is entered as "0.10" as shown in this
example.
Delete the example sales tax entry and enter tax rates for any jurisdictions where you must collect a
sales tax.
For more complicated tax requirements and data that is kept up to date consider commercial options.
There is a TaxWare integration in OFBiz, but this runs through JNI to talk to the native TaxWare libraries
(ie non-Java) and requires a lot of maintenance to use over time. Another option available in OFBiz is
support for the ZipSales tax database, which can be imported and then updates are imported on a
regular basis.
Shipping Settings
Each Store may have one or more shipping options configured. Shipping options consist of shipping
methods, shipping providers and rules which link methods, providers and cost estimate calculations. The
OFBiz e-commerce demonstration data is preconfigured with a number of shipping methods including
"Ground", "Air", "Next Day" and "None" and several well know shipping providers including, United
Parcel Service (UPS), the United States Post Office (USPS). In addition, templates for cost estimate rules
are provided to ease the customization process. Finally, OFBiz provides interfaces, and in some cases,
rudimentary configuration guidance, to allow the e-commerce store to connect directly and
communication with several major shipping providers.
4 Expert Recommendations: Similar to the tax calculation set up, the Shipping tab interface includes
many variables for shipping and shipping cost calculations. Note that at this time the user interface
provided through the OFBiz Catalog Manager is limited. This interface is sufficient for creating new
shipment methods and estimates. It is recommended that the provided examples be used as templates
for any new configurations desired, but that they be deleted and new ones created rather than trying to
edit them.
Selection of the Shipping tab brings up the primary shipping options page (Product Store Shipment
Settings) for the currently selected OFBiz store. A summary table of all the currently configured shipping
methods and estimates is displayed. This display includes the method type (for example, UPS, Ground,
Next Day and No Shipping), some basic estimate information (discussed below) and links to delete the
estimate for the method from the store (but not the shipment method itself) and links to view the details
of each estimate.
4 Expert Recommendation: select the "view" link on one or more existing methods to get a better
understanding of how shipping methods and cost estimates are constructed.
From the Product Store Shipment Settings page, there are two main sub-page links:
1. New Shipment Estimate

2. New Shipment Method
The New Shipping Estimate link allows the user to apply a new estimate to the store for an existing
shipping method. Shipping methods may have one or more estimates associated with them - ...For
example, if the default configuration for "Guaranteed Next Day (UPS) should be changed from no
surcharge for a specific feature group to a fixed surcharge for a feature group, this is the place to do it.
The New Shipment Method link provides access to the interface for modifying and creating new
Shipment Methods Types and Carrier Shipment Methods (where Carrier Shipment Methods are a
combination of a Shipment Method Type and a Carrier Party.)
The New Shipment Method page is the best place to start. Here you can create/update Shipment Method
Types, Carrier Shipment Methods (a combination of a Shipment Method Type and a Carrier Party), and
then at the top of the page you can associate a Carrier Shipment Method with the Store (this is where
most of the options are specified).
Once those are ready use the New Shipment Estimate page to enter price information (kind of like price
rules) about a specific Carrier Shipment Method associated with this store.
From either of these two pages you can get back to the summary of all of the cost information for these
estimates with the View Estimates link.
UPS Online Rate Estimates
This is used during the checkout process to get an estimate from UPS based on the weights of products
being ordered.
You must have an account with UPS to be able to use this service.
NOTE that products MUST have values in their Weight and Weight Uom Id fields for ALL products in order
for this to work properly.
If you specify an estimated cost along with this, based on whatever criteria just as with normal shipping
estimates, those values are added to what comes back from UPS.
This is activated by creating a shipping estimate record in the Catalog Manager with the Service Name of
"upsRateEstimate" on the ProductStoreShipmentMeth record in the serviceName field (ie on the Store
Shipment Method associating a Carrier Shipment Method with this Product Store).
For this to work the CarrierShipmentMethod.carrierServiceCode field must be populated (as it is in the
DemoShipping.xml file). Ground is 03, Air is 02, Next Day is 01 for UPS. For others see the
UpsServices.java file.
This is configured using various properties in the file:
${ofbiz install dir}/applications/product/config/shipment.properties
1. UPS XPCI Access License Number

1. o shipment.ups.access.license.number
2. o Example: TEST262223144CAT
3. o This license number is used for both the UPS shipment estimate online service and the
UPS XPCI shipping interface services (described below)
2. Shipper Default Pickup Type
1. shipment.ups.shipper.pickup.type
2. Example: 06
3. Valid options:
1. 01 - Daily Pickup
2. 03 - Customer Counter
3. 06 - One Time Pickup
4. 07 - On Call Air Pickup
5. 11 - Suggested Retail Rates (UPS Store)
6. 19 - Letter Center
7. 20 - Air Service Center
4. Choose the option that represents your relationship with UPS. This affects the
estimated rate you will get back since UPS varies their prices based on how you get your
packages to them.
3. Estimate split into packages
1. shipment.ups.max.estimate.weight
2. Example: "90" meaning 90 pounds
3. This number is used as the max weight per package when the total weight is > than this
weight the weights are split into packages not exceeding max.
UPS XPCI Integration
The UPS XPCI services provide for all interactions between a customer and UPS to register shipments,
send weight/size information for each package, get actual prices from UPS, and get images for complete
labels to print and affix to each package.
Note that UPS only offers this service to larger customers. The policy may have changed, but last I heard
daily pickups must be used and at least 50 packages must be shipped each day (each business day).
These services are integrated with the Shipment code in the Route Segments area and links in the user
interface appear when the Carrier Party ID is "UPS".
1. UPS Shipper Number

1. shipment.ups.shipper.number
2. Example: 486915
2. UPS Bill Shipper Account Number
1. shipment.ups.bill.shipper.account.number
2. Example: 486915
3. UPS XPCI Access License Number
1. shipment.ups.access.license.number
2. Example: TEST262223144CAT
4. UPS XPCI Access User ID
1. shipment.ups.access.user.id
5. UPS XPCI Access Password
1. shipment.ups.access.password
6. Setting to save files needed for UPS certification
1. shipment.ups.save.certification.info=true
2. shipment.ups.save.certification.path=/ofbiz/work/ofbiz/upscert
3. This option is used to create the artifacts the UPS needs to certify client implementation.
It is generally required for each customer to go through this process and for UPS to
verify the results. Once this is done the shipment.ups.save.certification.info property
should be set to false. For more information on this process, see the UPS XPCI
documentation and additional information in the UpsServices.java file.
USPS Online Rate Estimates
This is used during the checkout process to get an estimate from USPS (the United State Postal Service)
based on the weights of products being ordered.
You must have an account with USPS to be able to use this service.
NOTE that products MUST have values in their Weight and Weight Uom Id fields for ALL products in order
for this to work properly.
If you specify an estimated cost along with this, based on whatever criteria just as with normal shipping
estimates, those values are added to what comes back from USPS.
This is activated by creating a shipping estimate record in the Catalog Manager with the Service Name of
"uspsRateInquire" on each applicable ProductStoreShipmentMeth record (ie the Shipment Estimate
associating a Carrier Shipment Method with this Product Store).
For this to work the CarrierShipmentMethod.carrierServiceCode field must be populated (as it is in the
DemoShipping.xml file). Examples include "Priority", "Express", etc.
1. USPS Connection URL & timeout in seconds

1. shipment.usps.connect.url
2. Example: http://localhost/facility/ShippingAPI.dll
3. shipment.usps.connect.timeout
4. Example: 60
2. USPS Credentials
1. shipment.usps.access.userid
2. shipment.usps.access.password
3. Estimate split into packages
1. shipment.usps.max.estimate.weight
2. Example: 70
Store Payment Settings
This page is used to configure the payment processing settings for the various Payment Method Types in
OFBiz.
In the demo data you will see configured the test service for all payment methods, including Credit Card,
Electronic Funds Transfer (EFT), PayPal, WorldPay, and Gift Cards. It is important to remove all of the
"alwaysApprove*" and "test*" service references since those will allow bogus payments to go through.
The only demo configurations that can remain, assuming you want to use them, are the PayPal and
WorldPay settings. These don't use configurable services, so the configuration is simpler.
To setup Credit Card (and certain other payment types) processing just specify the services to use for
each of the following processes:
1. Payment Authorization Service

2. Payment Capture Service
3. Payment Re-Authorization Service
4. Payment Refund Service
5. Payment Release Authorization Service
All service definitions for the payment processing that are included with OFBiz are in the ${ofbiz install
dir}/applications/accounting/servicedef directory.
1. For CyberSource see the service definitions in the services_cybersource.xml file. This includes
these services: cyberSourceCCAuth, cyberSourceCCCapture, cyberSourceCCRelease,
cyberSourceCCRefund, and cyberSourceCCCredit
2. For ClearCommerce see the service definitions in the services_clearcommerce.xml file.
3. For PCCharge see the service definitions in the services_pccharge.xml file.
4. For RiTA see the service definitions in the services_rita.xml file.
5. For Verisign PayFlo Pro see the service definitions in the services_verisign.xml file.
6. For ValueLink (gift cards) see the service definitions in the services_valuelink.xml file.
Payment Processor Details
While the payment services and high level settings are configured in the Store section of the Catalog
Manager the detailed configuration for the various payment processing services are configured in the
file:
${ofbiz install dir}/applications/accounting/config/payment.properties

1. There are many comments in this file and sections for each of the major payment processing
services.
2. If you are using any credit card payment processor, be sure to check and if necessary change the
properties near the beginning of the payment.properties file that follow the pattern:
"payment.general.reauth.*.days".
PayPal Payment Setup
The PayPal details for OFBiz are setup in the payment.properties file and have the prefix
"payment.paypal.".
The ones that always need to be changed for use of PayPal are:
1. payment.paypal.business - set to an email address on your PayPal account

2. payment.paypal.notify - just change domain name and port to the production values you are
using
3. payment.paypal.return - set to the URL where you want PayPal to send customers once
payment is complete, typically back to your ecommerce web site
4. payment.paypal.cancelReturn - set to the URL where you want PayPal to send customers when
they cancel their payment
5. payment.paypal.image - set to the URL of the image or logo you want PayPal to display to help
customers know that the payment is being received on your behalf
The other properties beginning with "payment.paypal." can be set, but unless you know what you are
doing we recommending leaving them as-is.
In addition to the settings in the payment.properties file, there is also a setting that you must change on
the PayPal web site in your account so that notifications will be sent back to OFBiz to verify payment:
1. Login to your account at PayPal.com

2. Click on the "Profile" link in the header, near the top-right of the page
3. In the "Selling Preferences" column click on the "Instance Payment Notification Preferences"
4. It will show you the current settings. To chance click on the "Edit" button.
5. Check the check box near the top of this page, just under the "Instant Payment Notification
(IPN)" heading.
6. Enter the notification URL in the text box. This should be the same as the value of the
payment.paypal.notify property in the payment.properties file.
7. Click on the "Save" button.
CyberSource Payment Setup
1. The CyberSource details for OFBiz are setup in the payment.properties file and have the prefix
"payment.cybersource."
2. More details to come.
Giftcards Setup
GiftCard creation:
1. The giftcard is enabled in the productstore in the catalog as a payment method with several
parameters.
2. The productStore has a field called "Show Checkout Gift Options" this should be set to "Y"
3. In the entity 'ProductStoreFinActSetting' it can be set if the card requires a pinCode. By default
in the demodata this is set to "N"
4. The giftCard can be bought or reloaded as product in the product catalog.
5. If a giftcard is purchased a financial account is created for the new giftcard in addition to an
invoice and payment and ledger transactions. For this to work you have to activate the 'eca'
createFinAccountTrans in accounting/servicedef/secas.xml
Using the Giftcard as payment:
1. The giftcard code which is listed in the financialAccount

2. If the card is used with enough balance the Order gets rejected.
e-mail Settings
This page is used to configure the email messages to send for various events in the ecommerce system.
There is a record for each email in the system by default, but if there is an email that you don't want sent
you can Delete the corresponding record here.
For those you do want to keep you will want to change the following fields for each email message, one
at a time:
1. 2nd field, From Address, to your preferred customer contact email address
2. 4th field, Bcc Address, to any email address you would like to be copied on each email message
3. The other fields, like the 5th field, the Subject field, can be customized if desired.
If you want to modify any of the templates, we recommend that you copy the templates to your own
location, change them there, then change the template locations on this page to point to your files.
Survey Settings
This page is used to configure surveys that are used for various things in ecommerce including random
polls that show up on the side bars, special product related surveys to gather additional information
about specific products or products in specific categories, surveys associated with the customer profile,
and so on.
The demo surveys here can all be removed, though feel free to look at each one to see if it or something
like it might be nice to have on your site.
General Settings Override
This page is used to configure product search keyword overrides. These overrides can redirect the user
to a specific category, product, or OFBiz or arbitrary URL. For example, when a user searches for the
word "gizmo" they are redirected to the Gizmos category (ID 100).
The demo data in place is just an example and should be removed to avoid accidental undesired behavior
in product keyword searches on your site.
Catalog, Category, Product Setup
Catalog Setup
Rather than reusing existing Catalogs we will create a new one to associate with the Store we have been
configuring, and it will be the only one associated with the Store (unless you want to create multiple
Catalogs, of course).
To create a new Catalog:
1. Go to the "Main" in the Catalog Manager and click on the link labeled "Create New Catalog" near
the top of the central area of the page.
2. Enter an ID for the Catalog in the Prod Catalog Id field (this cannot be changed later).
3. Enter a name for the Catalog in the Catalog name field.
4. Unless you know you want to use the special Quick Add categories in this Catalog, I recommend
setting the Use Quick Add field to N.
5. The other fields are optional but can be used to customize the look and feel of this Catalog to
distinguish it from others (if applicable).
6. Submit the form with the update button.
Once the new Catalog is created, go to the Stores tab and make sure this Catalog is associated with the
Store we just configured.
While here, take a look at the Categories tab. We will soon be creating some Categories to use with this
Catalog. There are many types here, but the main ones we will be concerned with are:
1. Browse Root (One): this category will be the parent category of all of the top level browse
categories for the catalog. It will not be visible to the customer, but it's children will be the main
or top-level browse categories.
2. Promotions (One): the products in this category are listed on the default eCommerce Main page.
Of course, that page can be customized to show other things, but if you are using the default
OFBiz ecommerce templates main page, you should create a Promotions category to configure
which products will be displayed there.
3. Default Search (One): if a Default Search category is configured only the products in this
category will show up in product search results. This category can also have Feature Categories
and Feature Groups with it, and the Features in those groups will be used to populate the
parametric search drop-downs on the Advanced Search page. Of course, when searching within
a specific Category only the features associated with that category will be used for the
parametric search drop-downs in the Advanced Search page.
4. Purchase Allow (One): if a Purchase Allow category is configured only the products in that
category will be available for purchase when this catalog is active. In that case if a product not
in this category is put in the cart an error will be shown to the customer. In general for easier
maintenance it is best to have this set to the same category as the Default Search category.
5. View Allow (One): if a View Allow category is configured only the products in that category will
be visible when this catalog is active. Other products will not show up in search results, category
browsing, and if someone tries to view the product by ID it will report that no product is found
for this ID. There is a performance impact associated with the use of this category, so
alternatives might be desirable in certain circumstances. In general for easier maintenance it is
best to have this set to the same category as the Default Search category.
Category Setup
As described in the Catalog Setup section there are various basic Categories that we need to create for
our new Catalog. We will create four categories:
1. A Browse Root Category

2. A top-level browse Category to be a child of the browse root category
3. A Promotions Category
4. An "All Products" Category that will be setup as the Default Search, Purchase Allow and View
Allow categories for our catalog.
To Create a Category:
1. Go to the "Main" in the Catalog Manager and click on the link labeled "Create New Category"
near the top of the central area of the page.
2. Enter an ID for the Category in the Product Category ID field (this cannot be changed later).
3. All of these categories can use the "Catalog" setting for the Product Category Type field.
4. The other fields can be set, but are not necessary. Note that Category hierarchies do not use the
Primary Parent Category field, instead they are done with the Rollup tab once the Category is
created.
5. Submit the form by clicking on the update button.
Once the Category is created go to the Content tab and look near the bottom of the page in the Override
Simple Fields section to set a Description, and if desired also a Long Description.
For each of the categories that we are creating, go to the Catalogs tab in the Category section, or the
Categories tab in the Catalogs section and associate them using the appropriate type(s) as described
above.
For the top-level browse Category that will be a child of the Browse Root Category associate them using
the Rollup tab for whichever one you create second. Both parent and child categories can be setup there.
Product Setup
Congratulations, you are finally to the point where you can start setting up products....
To create a Product follow a process similar to those described for other things, like Categories.
1. Go to the main page of the Catalog Manager and click on the "Create New Product" link.
2. If you fill in an ID it will make sure that ID is valid, and if so it will use that one. If you specify
no ID it will generate one.
3. Set an Internal Name that makes it easy for you to recognize the product. This name will be
shown in the admin tools, but not to the customer.
4. Note that if you are using the UPS or USPS or other online rate estimation utilities then you must
have values in the "Weight" and "Weight Uom Id" fields.
5. Submit the form to create the product.
Add Content to the New Product
1. Click on the "Content" tab/button for the product you just created. Here you can setup text and
images for your product.
2. You will see some forms at the top for administering managed content (ie from the Content
Manager) with the product. For more advanced product related content needs use this, but for
more common and simple needs, this can be more difficult to administer and slower at run time.
3. Near the bottom of the page is a section labeled "Override Simple Fields". Here you will typically
want to specify a Product Name, Product Description, and Long Description. If you have images
to associate with the product, you can specify their locations here, or upload them. Note that
there are default locations for the images (can be quickly set by clicking on the "[.jpg]" or
"[.gif]" buttons). We recommend using these locations, but of course you can put your images
anywhere. These can be an absolute URL, or will be relative to the current server address, or the
content URL prefix if one is specified in the url.properties file.
Add Prices to the Product
1. Product pricing in OFBiz is very flexible. There are two main aspects to it: Prices and Price Rules.
This is independent of promotions, which are applied after the price calculation is done.
2. For basic operation you should have at least one type of price setup for each product: the
Default Price. This is the price that is used when no rules apply.
3. To add a Default Price go to the Prices tab for the Product, and use the form at the bottom of the
page.
1. The Product Price Type Id should be "Default Price", the Currency Uom Id should be
whatever currency the price is in, and the Product Store Group Id can be left as Not
Applicable, unless you are setting up multiple groups of stores that have different
pricing.
2. The From Date can be now or in the future, if you want the price to take effect in the
future. The Thru Date is optional, but can be used to specify that this particular price
expires at a certain date and time. Note that if there are multiple prices of the same
type, etc that are active at once, it will use the one with the most recent From Date. This
is useful when you want a temporary price to override the normal "Default" price of the
product.
4. If you are using price rules or may do so in the future you may also want to enter information
such as the List Price and the Average Cost which are often used in the price calculations.
5. Note that if a Minimum Price is set the price will never be less than that. So, even if the Default
Price is to 2.00 and the Minimum Price is set to 3.00, then 3.00 will be used as the calculated
price. The Maximum Price setting works the same way as the ceiling for the price.
Make sure to put each product in a browse category, and in the All Products category so that it can be
searched for, viewed, and purchased in your catalog.
Expert Recommendation: These are the basics, but there is a lot more information about products that
you can, or may need to, setup. We recommend reviewing the more detailed documentation or engaging
the services of an experienced consulting to help you through this.
Advanced Catalog Setup: Features, Promotions, Price Rules, Keyword Thesaurus, Features for special
functionality or parametric search, Moderated (or unmoderated) Product Reviews, Configurable and
Manufactured Products, Virtual and Variant Products, Inventory/Facility/Location settings, and so on
See the end-user documentation space for details on how to set these things up and what they mean.
Also see this for more advanced options for Products, Categories, and so on.
OFBiz Source Repository and

Access
View Repository
SVN - FishEye
SVN - Browse
SVN - ViewCVS
Subversion Links
Subversion Home
SVN Client Tools
Subversion Book
Anonymous (Guest) Access
Anonymous (Guest) Access
To connect to the OFBiz SVN Respository for anonymous checkout use your SVN
client command line tool:
• trunk : $ svn co http://svn.apache.org/repos/asf/ofbiz/trunk ofbiz

• release4.0 : $ svn
co http://svn.apache.org/repos/asf/ofbiz/branches/release4.0
ofbiz.4.0
Quicker download
or, for a quicker download, if you are just interested in a trunk or release snapshot
(not interested in keeping your local copy updated):
• trunk : $ svn export http://svn.apache.org/repos/asf/ofbiz/trunk ofbiz

export http://svn.apache.org/repos/asf/ofbiz/branches/release4.0
ofbiz.4.0
Alternative download
As an alternative you may download a "ready-made" package at Nightly Builds,

What Do I Get? . But using the SVN repository is the recommended way.
Developer Access
Developer access requires a special account which is provided by the OFBiz adminstrators. If you have
a developer account you can access the repository through HTTPS. When checking in, you will be
prompted your userID and password
Developer Access
• trunk : $ svn co https://svn.apache.org/repos/asf/ofbiz/trunk ofbiz

co https://svn.apache.org/repos/asf/ofbiz/branches/release4.0
ofbiz.4.0
When you first connect you will be prompted to accept the SSL certificate. Verify the certificate is for
svn.apache.org. After verification, select option 'P' to permanently add to your SVN configuration.
Subversion can handle keyword expansion, eol conversion as well as may other features. Most of these
features are configured on the client level rather than on the server. To make this easy on developers and
to provide a standard configuration, the official OFBiz Subversion client configuration file can be found
here: config . This file should replace the config file found in your $HOME/.subversion directory.
All users can access anonymous WebDAV either by pointing your browser or connecting your WebDAV
client to the same address as above:
WebDAV Access
• trunk : http://svn.apache.org/repos/asf/ofbiz/trunk
• release4.0 : http://svn.apache.org/repos/asf/ofbiz/branches/release4.0
ViewSVN Access
Public browsing of Subversion is available using the ViewCVS tool. You can access this tool from the
following link:
ViewSVN Access
http://svn.apache.org/viewvc/ofbiz/trunk/
The Old OFBiz SVN Repository
To connect to the OFBiz SVN Respository for anonymous checkout use your SVN client command line tool:
$ svn co http://svn.ofbiz.org/svn/ofbiz/trunk ofbiz

ViewSVN Access for the old repository is available here: http://svn.ofbiz.org/viewcvs
OFBiz Website Repository and Access (for committers)
To update the ofbiz.apache.org website and related xsd files:
1) check out the site files from svn: https://svn.apache.org/repos/asf/ofbiz/site/
2) update the required website and xsd files and commit
3) publish the updates:
• ssh to people.apache.org using your committer's account and password

• cd /www/ofbiz.apache.org/
• svn up
The mods will go live approx after 30 minutes.
To know more from ASF : http://www.apache.org/dev/project-site.html

Credits
The Subversion respository and JIRA hosting for the old servers, and the Confluence hosting is provided
by Hotwax Media, Inc and Contegix LLC . JIRA Professional license provided by Atlassian Software
Systems Pty Ltd . The new ASF SVN and Jira and other servers are hosted by the Apache Software
Foundation . Many thanks to all!
Framework Introduction Videos

and Diagrams
http://docs.ofbiz.org/display/OFBTECH/Framework+Introduction+Videos+and+Diagrams
These videos are QuickTime movies and use the new H.264 encoding. This provides great compression
while maintaining good quality. To view these videos you will need QuickTime 7 or later. These
movies are 1024x768 (8fps), and are recorded directly from the screen so the text should be
consistently readable. The video streams (H264) vary from ~150kbps to ~500kbps and the audio (AAC)
runs at ~32kbps.
NOTE: these files can be streamed, but chances are you will want to view them over time or multiple
times, so please save them as a local file rather than viewing the stream. The hosting for these is
sponsored by Contegix and Hotwax Media .
These videos cover an overview of the framework. For a complete coverage of the Apache OFBiz
framework take a look at the continuation of these videos in the Advanced Framework Package from
Hotwax Media. This includes 23.5 additional hours of video, a complete copy of the quick reference book,
and a complete transcription of both the Framework Introduction and the Advanced Framework videos.
The transcription is great for taking notes, reading along, and quick reference over time. For details see
the Apache OFBiz Advanced Framework Training Package . For this package plus 4 hours of remote
training to answer questions and such, see the Complete Remote Training Package .
Supporting PDF Documents (sponsored by Hotwax Media )
• Framework Intro Outline

• Example Data Model Diagram
• Quick Ref Book: Main Diagram
• Quick Ref Book: Artifact Reference Diagram
OFBiz Framework Introduction Videos (sponsored by Hotwax Media )
• 1: Introduction to OFBiz (3:03)

• 2: OFBiz Framework Overview (7:24)
• 3: Artifact Reference Diagram Overview (20:56)
• 4: Example Application Design Overview (12:43)
• 5: Entity Definitions (8:46)
• 6: Service Definitions and Implementations (15:40)
• 7: UI Artifacts: Request, View, Screen, Form (20:43)
• 8: File Details following Artifact Reference Diagram (12:22)
• 9: Doing Some Simple Changes (8:31)
• A: Where to go next? (3:17)

OFBiz Beginner's Development Guide Using Practice
Application
This is a very good article,please refer to the following URL:

http://docs.ofbiz.org/display/OFBIZ/OFBiz+Beginner%27s+Development+Guide+Using+Practice+Applic
ation

Best Practices Guide

Written By: David E. Jones, jonesde@apache.org
Table of Contents
• Introduction
• General Concepts
• Data Layer
• Logic Layer
• Presentation Layer
See Also
• HTML and CSS Best Practices

• Managing Your Source Differences
• Methodology Recommendations
• User Interface Layout Best Practices
Introduction
This documents presents best-practices for development and architecture related to The Open For
Business Project.
It will not try to cover all of the practically limitless options available for using tools in OFBiz and the
many related open source projects and standard APIs. It will also not try to cover all development
best-practices, just the ones most closely related to creating and modifying OFBiz based components.
It will try to cover the best practices for every layer of architecture and the best tools to use, and for
steps that should be taken prior to even laying out what code should be written. In some cases there will
be close seconds to the best practices that will be presented because in some cases these
second-best-practices will be more appropriate.
Note that this document assumes some knowledge of the OFBiz Core Framework. With some basic
knowledge it can answer a lot of questions about how certain things should be used. If you are not
familiar with the OFBiz Core Framework this will give you an introduction to it, but some things may not
make a lot of sense to you.
General Concepts
Reduce Code Complexity, Redundancy and Size
There are various techniques that can be applied to this problem that produce good results. The most
common, but least effective, practice is code generation. Because it is not something that I consider to
be a best practice, I won't discuss it further here.
The best practices that are used in various places in the OFBiz framework are dynamic APIs such as the
Entity and Service Engines, and special purpose languages like the Workflow and Rule Engines and the
MiniLang library.
The dynamic API pattern is characterized by a generic API with simple operations that behave differently
based on configuration and domain definition files. These are usually XML files. This is an alternative to
code generation and the input or domain description files used for generating code can often be used
unchanged to drive a dynamic API resulting in much less code and much more dynamic, ad-hoc control.
A special purpose language is used to create logic in a language or using a tool that fits the specific need
more appropriately than a general purpose procedural language like Java. This reduces code because it
is easier to describe what you want in a context that closely matches the problem that needs to be solved
than it is to use a generic language. High level conepts can be expressed without the need to write a lot
of code.
Generic Versus Special Purpose Artifacts
For OFBiz "out-of-the-box" (OOTB) the point for the generic artifacts (in all tiers of the application) is to
be as inclusive as possible. There is one reason for this: it is easier to know something is there and decide
you don't want it and then to remove it than it is to not know that it exists and either try to find it or end
up implementing it anew.
How do you decide which fields you want on a screen? It depends on the organization, and even more so
on the role within the organization.
There is no one answer for all users of OFBiz. There isn't even an answer for everyone in a single
organization (unless it is REALLY small).
This has been thought through and the OFBiz framework was designed very specifically to handle this
sort of thing. It is relatively easy to create user interfaces that are specific to certain roles within an
organization, and that is what OFBiz customization or creation of derivative works or creation of special
purpose user interfaces is all about. That's the very definition of it.
In all part of the framework the best practice is to first create a generic or general purpose artifact if it
does not already exist. For anything that is specific to a certain role within an organization or that is for
a special purpose the best practice is to derive the artifact from the generic one with as little redundant
code as possible using the many override mechanisms that exist in OFBiz. For the most part this can be
done without changing ANY of the base code from the open source project, making it easier to maintain
over time.
Data Layer
The best-practice tool to use in the data layer is the OFBiz Entity Engine. For most applications the Entity
Engine will elegantly do the work for 99% of your database interaction needs. In the few cases where the
Entity Engine is not sufficient I recommend using custom JDBC code for your queries or other commands.
That would be one of the second-best-practices that are sometimes needed.
When using the Entity Engine refer to entity and field names using inline strings. This makes it much
easier to read and maintain your code. If you need to prepare a large Map or EntityCondition to pass to
an EE method it is generally cleaner to do it on a separate line, or on various separate lines before the
actual EE method call.
Use a simple, normalized data model based on the needs of your applications. Usually the data model
can be driven directly by the requirements for the functionality that will use the entities. This usually
results in a highly normalized data model which will make your life much easier. When you need
combined data for reporting, use the view-entity feature to accomplish joins and grouping and
summarizing data.
Always use primary keys and avoid the use of generic sequenced primary keys when a more descriptive
composite key is possible. Always use relationship definitions to document how entities are used together,
to make it easier to get at related data, to constrain field by foreign keys, and to improve performance
through automatic foreign key based indexes.
Logic Layer
The best tool to use for invoking logic is the OFBiz Service Engine. Nearly all business logic should be
implemented as a service to improve reusability and facilitate component based development.
Even though services are very flexible there are cases where the service model is not appropriate, even
for business logic. In some cases calling a script or Java method directly is necessary and in those cases
using the service model would not make sense and should not be used.
The Service Engine reduces code size by providing many ways to use logic implemented as a service. You
can call your logic synchronously, asynchronously or on a schedule. When you are calling a service you
don't need to know where it is located or how it is implemented. This makes it easy to effectively
leverage remote services and services written using different languages. Being able to transparently call
logic in different languages through the Service Engine is important for the effective use of special
purpose languages.
When defining your services try to keep them as simple as possible using interface services or other
techniques. Whenever a service is based on an entity be sure to use the auto-attributes tag to create
attributes from the entity field definitions. Also, rather than redefining attributes using the attribute tag,
use the override tag and only specify the information you want to change.
Always implement your service using the easiest and most appropriate language or tool. You can
implement services with many different languages including Java, Groovy, Beanshell or any BSF
compliant scripting language (Jython, Jacl, JavaScript, etc), OFBiz Workflow Engine processes, OFBiz
MiniLang simple-methods, and various others. Additional languages can be supported by writing simple
adapters.
Most services are oriented around data mapping and handling and the simple-method is the best way to
implement them. Writing a service with a simple-method is the primary best practice for writing a service.
There are some cases where simple-method scripts are too restrictive or cumbersome, and in those
cases a more general purpose language should be used. The two recommended secondary best practice
tools for this case are Groovy and Java, with Groovy being preferred because of flexibility/extensibility
features, no recompilation needed to test changes, and various other benefits.
Always call remote logic through the Service Engine. You can call remote services through various
mechanisms including HTTP, SOAP, JMS, and others. You can also add remote service invocation
mechanisms by creating a simple adapter.
Most of the time you will want to let the Service Engine automatically wrap your service call in a
transaciton so that the whole thing will succeed, or the whole thing will fail. Note that if you call a service
inside an existing transaction it will recognize the current transaction and use it instead of trying to
create another one.
Presentation Layer
Always separate input processing logic, view data preparation logic, and view presentation templates.
This will make it easy to reuse logic not only in web applications, but also for independent fat client
applications. It will also make it easier to organize your code and find a specific piece of functionality
when debugging or exploring to find out how a component works.
For each of the three separate pieces there are special best-practices tools to use.
Input Processing Logic
Input processing logic should always be associated with a request in the controller.xml file and never with
a view. Input processing logic should generally be implemented as a service and called through the
service event handler which will automatically pull data from request parameters or attributes and
convert it from a string to the object type defined in the service definition. This makes it easy to specify
which parameters you care about processing just using the service definition, and let the framework get
them ready for you.
There are various cases where input processing logic cannot be implemented as a service. There are
various other types of event handlers for logic associated with requests that give you more to the request
context and are not environment agnostic like services are. One example is receiving uploaded data.
Another good example is doing special pre-processing and validation on parameters before passing them
to a service for processing. Note that you can always call services from these custom events and
wherever possible generic logic should be implemented in services.
Always let the Control Servlet configuration handle decisions about the appropriate response to take for
a request given the result string from an event. In most cases the response will be the generation of a
view, but sometimes it will make sense to chain requests together to acheive logic reuse or more
advanced flow control.
View Data Preparation Logic
View data preparation logic should always be associated with the view template it is meant to prepare
data for. This should be done through the OFBiz Screen Widget in the screen definition XML file by
specifying a script action. When a screen is split up into multiple templates or screens the data
preparation action should be associated only with the individual small screen that it prepares data for.
This makes it easier to move templates and content pieces around and reuse them in many places.
View data preparation logic should be specified as actions in the XML screen definition or if necessary
implemented in a dynamic scripting language such as Groovy, JavaScript, BeanShell, Jython or Jacl to
make it easy to modify the user interface on the fly. Generic data retreival should be implemented as
services which should be called from these dynamic action scripts. This makes it easier to share and
reuse this functionality in multiple pages and in other types of user interfaces.
The best practice in OFBiz for data preparation is to use one of these tools:
1. for simple data retrieval: the entity* tags in the screen action section
2. for more complex data preparation and manipulation: simple-method or Groovy
3. for larger data preparation and more reusability: implement a service and call in a screen action
tag
When preparing data in view actions you should make the data available to the view template by putting
it in the "context" object. All attributes in the context object will be made avilable in the context of the
template, if the template languge supports that.
While the use of JSP is not recommended in OFBiz, it is supported. Note that when using JSP for a view
template you cannot use the Screen Widget so the actions facility will not be available. Our
recommendation for JSPs is to have a single scriplet at the top of the page that prepares the data. In this
case try to call worker services or worker Java methods to do most of the work and to keep as much logic
as possible out of the page.
View Presentation Templates
The best-practice template engine that we recommend for HTML and other text generation is FreeMarker.
It is like Velocity from Jakarta, but much more flexible and fits in nicely with other OFBiz Core Framework
tools. Rather than running FreeMarker templates directly we strongly recommend using the OFBiz
Screen Widget so that actions can be associated with screens and they can be decorated with common
templates. We'll describe how to best use this below.
The view presenation templates should always be kept as simple as possible and common content such
as headers, footers, sidebars, and so on should be added at run-time using the decoration pattern. The
template file that should be used to decorate each page is specified in the screen definition XML file.
Always use the view generation tool that most closely matches your needs. FreeMarker is the
recommended tool for generating text output, but there are many situations where other tools are more
appropriate. If you want to use other text generation tools such as Velocity or XSLT we recommend you
do so through the Screen Widget, especially if you want it to be decorated and have actions run to
prepare for the templates.
When you want to display report like views we recommend using the Screen Widget along with
FreeMarker to generate an XSL:FO XML file, and use the Screen Widget FOP view handler in the Control
Servlet configuration to transform it into a PDF to send to the client. This approach allows you to use the
same tools for these reports as with other views in your applications and offers essentially unlimited
flexibility. As an alternative you can use other more traditional reporting tools such as Jasper Reports or
DataVision and mounting those reports through a view-map in the Control Servlet configuration file
(controller.xml).
If you have UI patterns that are repeated frequently such as forms, query data displays, tab or menu
bars, expanding tree views, and so forth we currently recommend using an XML file to describe the UI
pattern and then transform it to HTML or other output using a rendering engine for that specific XML
format, or using XSLT/FreeMarker/etc to transform it into the desired output.
For most forms the best way to represent them is to use the OFBiz Form Widget which accepts a generic
form definition in XML that is usable with multiple user interface types, and that takes advantage of
existing assets in your OFBiz based code such as Service and Entity definitions. This results in code that
is much smaller and easier to maintain.
When using FreeMarker is not possible or practical we recommend using another dynamic templating
language such as Velocity. When that is also not possible or practical we recommend using JSPs. But,
note that when using JSPs you cannot take advantage of the actions or decoration templates because
you cannot run it through JPublish. This is thanks to limitations in the JSP specification. Even through you
cannot use the decorator patter, you can use the composite view pattern with the OFBiz Regions
framework. Regions are specified in the regions.xml file. Note that these are not as easy to use as Screen
Widget composite views, and they do not support actions. But the Regions framework does offer a lot of
flexibility and is very useful in many cases.
HTML and CSS Best Practices
Web Standards and Browser Compatibility
OFBiz HTML and CSS code should strive to conform to the latest W3C standards. Browser-specific
extensions should be avoided.
If a particular browser does not conform to the latest standards, then the HTML/CSS code should strive
to produce a usable web page with that browser. In other words, OFBiz developers should not "dumb
down" the user interface to support a non-conforming browser, yet someone using a non-conforming
browser should still be able to use OFBiz.
The internal applications (all of the managers) should work well in standards compliant browsers. Don't
worry too much about coding to older browsers in those applications.
The public/customer facing applications (such as eCommerce) should be initially developed to be

standards compliant and work in standards compliant browsers. However, for these applications we can't
stop there. The fact is, much of the consuming public uses a variety of browsers and it is necessary to
create sites that work well with them. Doing so shouldn't break the standards compliant code, but it may
require browser-specific variations in order to work well with the needed browsers
HTML Guidelines
HTML should be well structured, concise, and free of styling information. Well structured HTML is easily
styled with style sheets (CSS) - therefore all styling code should be kept in the style sheets.
Using HTML tables for general layout should be avoided. There are HTML "element collections" within
OFBiz that need a table style layout (such as forms), so their use in those cases is acceptable. As future
CSS/HTML standards come out, the use of tables for layout should disappear.
All HTML should pass validation.
CSS Guidelines
Style sheets should be concise and organized.
Build from the bottom up. Assign common properties to basic HTML elements first, then embellish the
elements with additional selectors (CSS inheritance).
Give the class names/selectors meaningful names that describe what they are styling. Class names
should be easily understood by non-technical people - such as graphics artists. Class names should not
imply positioning or styling. Examples of improper class names: "topRightButton" "leftMenuBar"
"boldRedText" - those all imply position/style.
Recurring HTML element collections (navigation bars, button bars, screenlets) should be styled as a
whole - using contextual or descendant selectors. In other words, styles should be applied to containers,
and the container's style should style all of the elements it contains.
Be consistent with property values. Use EMs for sizing - which allows the page to be resized gracefully.
Use the hex notation for colors - which allows a graphic artist to search/replace colors.
HTML/CSS Testing Guidelines
Test your code on several browsers, then change the browser's settings (such as default font size).
Reverse the layout direction (CSS direction: rtl; ). Change the language. Resize the browser window -
make it really tiny. The page should make sense under any circumstance.
After you're satisfied that your HTML/CSS code will display correctly under any circumstance, run the
page through a validator to catch any errors.
Managing Your Source Differences
When customizing OFBiz components for your specific business requirements you will most likely come
across situations where small changes to files are needed and it doesn't make sense to replace a
component completely or attach logic to it through Service ECA rules or other means. So, how should
you manage the differences between your code and the OFBiz baseline code so that updating from the
OFBiz baseline will be as painless as possible?
The first thing you should always do is isolate your chagnes and comment them so that it is easy to
distringuish what you changed from the OFBiz baseline code. The final goal is to make it easy to merge
your changes with future changes in the OFBiz baseline.
There are various ways to structure your internal CVS or other code repository. One very flexible, but
laborious, way is to create a complete copy of the OFBiz CVS tree in a module in your own CVS repository.
This could perhaps be called "ofbizbase". This should contain the revisions of the code that you are
currently working with and allows you to selectively incorporate specific changes from the OFBiz baseline.
These files should be direct copies from a revision in the OFBiz CVS repository. If you make changes in
this module that are not part from the OFBiz baseline they should be temporary changes that are meant
to be overwritten and replaced with future versions from the OFBiz baseline.
Once your ofbizbase snapshot module as described above is in place you should create another module,
maybe called "ofbizdiff". This will contain ONLY the files that you have changed relative to your ofbizbase
module. When updating the version of a file in your ofbizbase repository from the OFBiz baseline you
should do a three way diff/merge to make sure the changes in the OFBiz baseline make it into the version
of the file in your ofbizdiff module as well as the file in your ofbizbase module.
The three way diff/merge will be done with the following three files: the old file from your ofbizbase
module as the base, your changed file in your ofbizdiff module as the merge target, and the new file from
the OFBiz baseline as the merge source.
The build process for this sort of a structure is very simple. Create a temporary build directory. Copy the
entire ofbizbase tree into the directory. Copy the entire ofbizdiff tree into that directory, replacing files as
needed. In the root of the temporary build directory run the Ant build file. What could be more simple?
When editing files in your ofbizdiff module you should ALWAYS edit them in place in the ofbizdiff directory
tree and copy them to the temporary build directory for testing. Doing this you will always be able to do
a CVS update to see which files you have modified as you are working.
Many variations on this technique can be effectively used. If you don't plan to make temporary changes
to ofbizbase files or update individual ofbizbase files selectively, you may do just fine with an archive (like
a zip or tar.gz file) instead of a CVS module for your ofbizbase tree. You could keep the current version
of this archive in your ofbizdiff CVS module.
We have heard a lot of questions about using simple merge scripts to apply differences to source in the
ofbizdiff tree so that full files do not have to be stored ant maintained there. This is fine, but it is a LOT
harder to perform the diff/merge or other code synchronization when you don't have the complete files
to do a three way diff/merge. So, we don't recommend using minimal diff files that can be applied as part
of preparation for the build process. Just copy the file from ofbizbase to ofbizdiff and make the changes
you need as recommended above.
For Those Comfortable With CVS

Branching/Merging
If you are comfortable with the branching and merging features in CVS you can use those very effectively
to easily maintain you differences from the OFBiz base source tree, and still keep up-to-date with the
latest from OFBiz without too much trouble. CVS does three-way diff/merge operations all the time when
doing updates, and this same feature can be used to do the three-way diff/merge described above, but
in an automatic way that only requires your involvement for merge collisions.
To get started do a fresh checkout from the OFBiz CVS repository, then remove all CVS directories and
import the tree into a new module in your local CVS repository. Tag this set of files with a name like
OFBIZ_20030612 (adjust for the current date) using a command like "cvs tag -b OFBIZ_20030612".
Now just change/add things as you please. Note that you are not working on that branch, you are
working on the HEAD branch unless you do something like "cvs update -rOFBIZ_20030612".
So, now you have a bona-fide branch of OFBiz with your own code mixed in, but there are a ton of cool
new things in the latest OFBiz base code that you would LOVE to have. What do you do? The easiest way
to do this is to use the "cvs import" command, and you can do this multiple times to get a new vendor
branch for the latest OFBiz code. For example, checkout the latest OFBiz code (with an export or a
checkout) and from the root directory of that import run something like 'cvs import myofbiz OFBIZ_BASE
REL_3_0_0 -m "More cool stuff from OFBiz"', where myofbiz is the name of your local CVS repository
module, and OFBIZ_BASE string you use to identify this vendor branch, and REL_3_0_0 is a string you
use to identify the current set of code from OFBiz. This could also be date based if it isn't from an official
OFBiz release or tag.
Go back to the place on your machine where you have HEAD checked out and merge the branch you just
created with the HEAD, or the current set of files you have checked out. To do this run something like "cvs
update -dP -j[the-ofbiz-tag]".
At any time to get a list of all files changed from the base, get a list of all tags on the module and compare
the HEAD revisions with the revisions tagged using the most recent OFBiz tag.
Methodology Recommendations
Before you can build something that something has to be defined. Every detail has to be decided at some
point. Because of the difficulty of communication between individuals and the difficulties that are
inherently involved in complex systems we recommend various practices.
While these techniques are used for some components in the core Open For Business functionality they
are primarily meant for those who are creating derivative works based on OFBiz. The reason for this is
that OFBiz is a generic framework, set of application components and suite of applications. In many
cases these applications can be used as is but they are not meant to be everything to everyone. Because
of this work will likely be needed for derivative works that are targeted at a specific industry, type of
business, or specific end user.
Methodology: Keep it simple, but not too simple
There are dozens of different software development methodologies, and more are being introducted all
the time. There are lots of good ideas presented in the hundreds, or even thousands, of documents
available about different methodologies. In general we recommend the "agile" approach, but that needs
to be qualified given the different perspectives that have been attached to that name. In general we
recommend keeping it as simple as possible, but not too simple. For more specifics on agile software
development see the Agile Alliance web site.
So the big question is generally: what is the minimum that we need to handle this project? The more
methodology you have the more time and money you will spend on it. The less methodology you have
the greater the chance that the requirements of the project will not be satisfied.
Minimal Roles
There are really only two roles necessary for any project: a buyer and a seller. In the case of software
projects, and other service offerings, the more common terms are customer and developer. Those are
the terms that will be used in this document. The term developer is used loosely here and refers to
anyone that produces actual deliverables. The term customer is also used loosely here and refers to
anyone that specifies what will be done and pays for it to be done. In some cases the customer and
developer will be the same person, or the same group of people.
It should be noted here that an important part of the "customer" role is the actual target user(s) of the
software. If possible reviewing stories and use cases (as described below) with users should be done.
Interviewing those who are currently performing tasks that will in the future involve interaction with the
new system can make it much easier to acheive complete and effective results. This is true on many
levels. For instance, the best usability can be acheived by reviewing screen/page prototypes with real
users and then validating final deliverables with real users. If the user group is large this may require a
lot of work to get a good sampling of the different users of the system.
In many projects the two roles, customer and developer, will consist of groups of people and other roles
will be introduced within the groups to clarify responsibilities. In these cases the methodology may also
have to be more significant to keep things from deteriorating into chaos.
One practice that can reduce the need for a complicated and detailed methodology is to have one person
from each group act as the agent for the entire group. Of course, that agent should discuss things with
the rest of the group, but if the number of voices for interaction between the groups can be consolidated
to one then communication and management of details will be much easier.
Note that for large projects having one agent for each side will not be practical. In those cases dividing
the scope of the project and likewise dividing the customer and developer groups will be necessary.
Another variation on this is where a group creates a product targeted at hundreds or thousands of
customers. In this case the "customer" that defines the product will be part of the same organization that
produces the product. Given the definition of customer above the sales, marketing, and testing groups
should be in the customer group, and an agent from that combined group should coordinate with the
development group.
Minimal Communication
The biggest trick with communication is to find the balance between to much and too little
communication. The burden for this is generally on the customer because it is customer that specifies
what will be build. Like I said at the beginning of this section everything that will be built MUST be defined
sooner or later. Anything that is not specified by the customer can be handled in one of two ways. The
developer can decide what will fit into the gaps or the developer can request clarification and details from
the customer.
To facilitate communication and make sure that the final result satisfies the needs requested by the
customer the following process is recommended.
Minimal Process
One important aspect of this process is that it should be repeated frequently and the scope for each pass
should be kept small so that when miscommunications occur they can be identified and resolved quickly.
While this process is simple and involves simple roles and artifacts it can be used as a skeleton for a
much larger and more detailed process. Each step can be divided into many steps and extra steps to
compensate for the needs of a specific project can be added.
Also note that this general process is the basis of the Work Effort components that are part of OFBiz and
those tools, as well as many other available tools, can be used to make artifacts and other information
easier to manage.
1. The customer requests features by telling a "story" about each feature desired.
2. The developer creates one or more requirements for each story by writing a more formal "use
case" describing in detail how the resulting component(s) will be used.
3. The customer reviews the use case(s) and provides feedback to the developer if necessary. If
feedback is returned the developer adjusts the use case(s) and resubmits them to the customer.
When the customer is satisfied the requirement is approved for implementation.
4. The developer defines tasks that must be done to create or modify components in order to
satisfy the approved requirements. At this point, if desired, time and/or cost estimates should
be associated with the tasks.
5. The customer can specify priorities on the request, requirement or task level. Given that tasks
may have dependencies the actual order may be changed by the developer such that
prerequisites are satisfied first.
6. The developer does the work described in each and demonstrates the result to the customer. To
improve developer productivity interruptions during this time should be minimized, except of
course interruptions related to changes in what is to be done for that component. The actual
time and/or cost should be recorded at this point if desired.
7. The customer reviews the deliverable and either approves the work or requests adjustments as
needed in the story, use case, and/or tasks. Making adjustments at this point involves going
back to previous steps and then the same subsequent steps should be followed to complete the
process.
You will notice that this process involves a great deal of customer interaction. If done right the customer
and developer will interact on nearly a daily basis. For coordination and management periodic meetings
should be held to review new requests or changes to existing requests and to adjust priorities as
necessary. These meeting should be held once every one or two weeks for most projects.
After looking at this list you may have questions about what constitutes a story, use case, and task.
A story is essentially an informal free form document from the customer that describes what is desired
in complete sentences or as an outline. Precise details are not needed at this stage. Note that this
document may change to be more precise or to include additional aspects. This document will be used to
create more formal use case(s).
A use case is a document that contains detailed information in a more formal structure and represents
the complete specification corresponding to one or more stories. A use case should include the following:
• The primary and other actors, defined by the roles of the the users or systems that will be
interacting with the functionality
• The goal(s) of each actor and/or the overall interaction
• Usage scenario(s)
o The primary actor
o The goal of the scenario
o Conditions that trigger the scenario
o The result(s), includes both success and failure results
o Scenario variations
o Errors, exceptions, and resulting actions
Note that for simplicity scenarios should be kept small and include only the minimal basic process.
Variations on process should be defined separately. Exceptions and errors in the process should be
defined separately along with their results.
Defining tasks is generally fairly simple and should be done by the developer in a form and using terms
that the developer will understand. There is a lot of meta-data that is generally associated with such a
task. Examples include estimated and actual time and cost, start and end dates, all parties performing
or otherwise involved with the task, and so on.
Conclusion
Some basic preparations should always be done before getting into the implementation. Some basic
principles and a basic process has been presented. Because of the nature of how most projects work all
of the steps in the process will be done in one way or another. Following this process does not require the
creation of any written documents, although in many cases that will help quite a lot. It can be done
through verbal conversation, or even a series of thoughts inside one's head.
The process described is meant to be customized to your needs. Following it as is should do for most
medium sized projects. When there is only one or two individuals involved, or tens or hundreds of
individuals, changes will obviously be desired. When modifying the process keep in mind the basic
principles presented and be especially careful about leaving out communication steps, espcially the
communication verification steps.
User Interface Layout Best Practices
In order to present the user with a consistent user interface (UI) certain guidelines or best practices
should be followed. The guidelines presented here are intended for the back office (manager)
applications. Layout for public-facing screens (such as eCommerce) are typically customer-defined and
will have different guidelines.
Navigation
OFBiz navigation is separated into four main categories, and some screens may have others. Navigation
links should appear only for targets that the user has permission to access.
Main Navigation
This section (in the header of the screen) contains links for business and end-user oriented applications.
Links to less frequently used and more technical applications are kept in secondary navigation. The main
navigation area should indicate which application is currently selected if the current application is linked
to from here.
Secondary Navigation
This section (in the footer of the screen) contains links for less frequently used applications. The
secondary navigation area should indicate which application is currently selected if the current
application is linked to from here.
Application Navigation
This section contains the application's title, plus links to functional areas within the application.
Application navigation should indicate which area is currently active.
Application Area Tabs
This section consists of tabs that split up a single area of an application into multiple screens that all fit
together and are generally parameterized with the same parameter or set of parameters (for example
the productId for all of the Product and related tabs). The tabs should only include screens that are part
of the set of screens for the area. Links to screens that are not part of the set of screens for the area
should be included in the links below the tab bar.
Guidelines for Main Screen Areas
Main Screen Area
The Main Screen Area is the area inside the decorator that changes for each area of an application. In
other words it does not include the header or footer, or side-bars if the application has them.
This area of the screen is focused around whatever task or process the user is performing. If multiple
tasks are used in a single screen, they should be clearly separated.
Generally speaking, the main screen area should contain the following items, going from top to bottom:
1. Optional application area tab bar (mentioned above).

2. Page title, using the h1 style. The page title displayed in the main content area should match the title
bar title. This makes a strong connection between screens and bookmarks and browser history.
3. Optional related screen buttons, in the button bar style (external links outside of a certain set of
screens). For instance, a Find screen might have a "Create New" button here.
4. The main form or other interaction area.
Many screens will fall into a few general categories, and those categories are detailed below.
Create or Add Screens
Create or add screens should contain the following items, going from top to bottom:
1. Optional application area tab bar.

2. Page title, using the h1 style.
3. Data entry form, including a Save button.
Avoid having unnecessary controls on the screen. For instance, a create screen should not contain a
"Create New" button on it - that would be redundant.
In some cases, screens with a create form also contain a list of existing items. If it is used the item data
entry form should be above the existing item list. In addition, the item data entry screen should be
collapsible and initially collapsed. If the new item form area is not collapsible it should then be below the
list form with existing items.
Find Screens
Find screens should contain the following items, going from top to bottom:
1. Optional application area tab bar.

2. Page title, using the h1 style.
3. Optional related task buttons, in the button bar style. For instance, a "Create New" button.
4. Optional Search Options data entry form. The form should be collapsible, and collapsed when a find
has been done and there are results for it.
5. List of found items - the search results.
Using the FindScreenDecorator is recommended - it will facilitate correct layout and will reduce screen
widget code.
The initial display of search results is controlled by the widget.defaultNoConditionFind property in the
widget.properties file. If a specific behavior is desired regardless of that setting the noConditionFind
should be set in the screen actions.
Comments
Here are some recently discussed options

• Links in screenlets . Many ideas came from this thread
o The main and origal idea was to have less (or even none) buttons in header
o It was also suggesteed to use screenlet like how gmail does. Notably
Three buttons max
Dropdown for other actions
The idea of duplicating at bottom
o Having breadcrumbs under the title bar
o Using portlets in place of screenlets
• OFBiz Theme Gallery . The idea is to create specific maincss.css under a folder structures like
/framework/images/webapp/images/themes/theme1/maincss.css
/framework/images/webapp/images/themes/theme2/maincss.css
and to have a property in general.properties file (or somewhere else like user's preferences
setting) to select a theme at will, default being the one currently used in OFBiz stock.
• Web tools
o Entity Data maintenance
have vertical separators for columns when viewing entity content,
make the Find options a collapsible screenlet,
make styles of the Entity Data Maintenance screens in general the same than
used by the widgets.
o At large, maybe restyle all the Web tools page (not a priority)
• Introduce Mashups
• List : to have in the results list form of every FindScreen (optionally) a first column of check
boxes that let the user to select several items and than a combo box above the list that let the
user to
select a command to execute on them.

OFBiz Contributors Best Practices
Why You Should Contribute to OFBiz
By contributing your improvements back to OFBiz, you can get our entire community of developers and
users to help you debug, improve, or extend the features that you need for your business. Furthermore,
if your contributions improve OFBiz, then it would help to attract more users and more developers for
OFBiz down the road, and eventually those users and developers would make contributions that would
benefit you. Finally, the process of contributing back to the project is a great way for new users and
developers to work with the existing community and learn more about OFBiz so they could tap into its
power and flexibility.
How to Contribute to OFBiz
OFBiz is a community-developed open source project. What that means is that we're looking to you, the
user, to help make our application better. Anybody can contribute to OFBiz, you do not have to be a
committer, on an "approved" list, or be a friend or relative. All contributions are considered based on
their merit for the project. You also do not need commit privileges to make a contribution. Just create a
patch file and post it on our JIRA issue tracker .
How to create a Jira issue
1. Create an account here , if you do not have one

2. Login
1. (optional)Search if an issue for what you are after already exists
by using the "Find issues"
2. (optional)If an issue on the subject already exists you can add a
comment on it
3. If a issue does not exist, create a new one selecting the "create new
issue" command. For details on the issue creation see here
4. Select the OFBiz project and the issue type.
5. Fill in all fields, give as many detail you think necessary
o Generally it is very important to select in the "Affect version" field
the ofbiz version you are running. If you are running the trunk
then the SVN revision should also be specifyed in the
Environment field
o Use the Environment field to specify at least your operating
system and the database ofbiz is using since these information
could be very useful to help people to work on the issue
6. If you need to attach files such as patches you must do it as a second step
after the issue creation. It is also possible to easily attach screenshots to
the issue see here
o When attaching files or screenshots you can add a comment
where you explain how the attached file is supposed to be used.
Please reference the file name in the comment because more
files could be attached to the issue at a later time and they will be
all listed togheter far from their comments.
o Also please use preferably .patch as extension for patches. If
updating an attached file keep the same name : Jira is able to
deal with that and will simply gray old files, you don't need to
delete them (sometimes its usefull to compare older patches
versions)
7. Jira offers a voting mechanism that is used to give more relevance to the
issues (see here to learn more)
When to create a Jira issue
1. Before creating any Jira issue, please check, using some related key
words, if a similar issue does not exist already. For that you can first use
the quich search at top right of Jira pages and after refine your search
using relevant information. For instance by default all projects are
scanned, you may then search only in OFBiz, etc.
2. If you already have a patch for an improvement/fix then create a Jira
issue (if there is not one already) and attach your patch to it
3. If you don't have a patch, and you have discovered a bug, create a Jira
issue (if there is not one already) providing as much details as possible
(including the rev. number and the environment you are using, and the
step to recreate the bug)
4. If you don't have a patch, and you have want to suggest an enhancement
or new feature, then discuss this in the dev mailing list instead of creating
a Jira issue; at the end of the discussion, the community will consider if a
summary of the thread should be saved in a new Jira issue, to facilitate
future development
5. If you don't have a patch, but you are planning to work on it, and you
want to share your design details with the community, you should discuss
this in the mailing list instead of creating a Jira issue; if, on the other
hand, you don't have time to do this, you have already decided that you
want to implement your patch following your design notes, and you just
want to let the community know about the upcoming patch, you can
create a Jira issue (to which you will attach your patch when it is ready);
Summarizing:
• Bugs: always create a new Jira issue everytime you find a new bug
• New features/enhancements: create new Jira issue only if you have a
patch (or if you plan to submit it very soon)
If you become a frequent contributor and are willing to help with the long term development of the
project, you could become a project committer.
The following guidelines are meant to help contributors work with the committers and the community as
a whole:
Guidelines
1. Follow coding conventions. Seriously, read that document.

2. Install the OFBIZ Subversion client configuration file
3. Follow the 2 main rules for committers:
1. Rule #1 for a committer is the same as for a doctor: first
do no harm. Nothing should be committed that breaks existing
functionality without replacing it either before or in the same
commit. Whatever you are working with someone developed it
and chances are someone is using it, and possibly MANY people.
2. Rule #2 for a committer is the same as for a scientist:
read before you write. When you're getting started a good
time ratio for read to write is around 20 to 1. Once you're a total
OFBiz pro who knows as much as any living person about the
project, you can probably reduce that to about 3 to 1.
4. Discuss your features with the community. What are you trying to
implement, and how are you planning to do it? This is especially
important if you are new to the project.
5. Write clear, well-commented and understandable code. Don't take
shortcuts, especially around variable names and error or warning
messages. Use understandable data structures. Remember, somebody
else will be working with your code down the road.
6. When you prepare a patch, do your best to avoid to mix formatting
changes with relevant changes (if possible, provide a separate patch
containing only formatting changes): in this way the reviewer's work will
be easier
7. When you prepare a patch, do not insert in the code comments with
author information since your name will be recorded in the commit log
(that is the place were we store this kind of information)
8. Internationalize your code with UI labels.
9. Start out with small contributions which are easier to review. In the
process, get familiar with the project's coding style and "thought
process."
10. Keep patches and contributions easy to review and commit. Even if a lot
of code is touched, try to keep things isolated and the intent of the
patch(es) clear. Remember that most committers can find 20 minutes
here and there, but it is very hard to fit in the 2-4 hour time block required
to review and commit a larger patch (especially if it touches ANY lower
level or more sensitive or complex artifacts, and this requires more
thorough review).
11. Put your contributions on JIRA instead of emailing it directly to the
committers, so everybody can review and comment on it. Though it is not
necessary this makes contributions more traceable for the licensing
through the Apache Software Foundation.
12. Get other members of the community to try your patch. Write the dev
list and tell them what you've done and ask them to try it out and vote
for it. This will help the committers when they are reviewing your patches
as there will be more confidence that the patch does what it is intended to
do, and doesn't break anything else.
If you are planning a larger contribution, please follow the following tips to facilitate both licensing and
collaboration. These tips will make it easier for committers to review and incorporate your work, and will
overall speed up your development process as you'll be asking the OFBiz team to do a number of small,
simple tasks rather than a couple of large tasks that a committer will have to find significant time to
review and commit.
Tips
1. Do not implement large blocks of artifacts (code, etc) on your own and
then contribute them to OFBiz.
2. If you have a large block of code to contribute we can work with you on
that, but it requires a different review and legal vetting process than
normal contributions, as described
on http://incubator.apache.org/ip-clearance/index.html .
3. When a method is deprecated, it should be explained which method
should be used, and what has changed.
4. Instead develop and contribute as you go. This means develop as you
would normally, but interact with the OFBiz community through mailing
lists and contribute patches regularly. # If you are do not have a
committer on your team this can slow down development, so do what you
can to "sell" one of the committers on your project and get an ally on the
committing team to regularly review and commit your patches. Note that
if you let us know in advance that you are planning a larger effort of this
nature, we can perhaps find a volunteer beforehand to work with you on
this.
5. Just please remember that there is no paid staff on OFBiz, all are
volunteers. You may see your patch sit in Jira for a long time while
committers work on other things. This usually happens because a
committer is working on a priority for the project that has been a problem
for a while, or on a paid contract in order to survive and to be able to
continue helping with OFBiz.
6. It might be tempting to run your effort without getting an OFBiz
committer involved, but keep in mind that committers can help you with
technical, business, and legal concerns either on their own or through
collaboration with others in the project on in the ASF more generally.
A more advanced topic should be also noted here.
Deprecating entities
Whenever we deprecate an entity in OFBiz there are certain things that MUST be
done or all committers should reject the patch:
1. rename the entity to deprecate by adding an "Old" prefix to it, then

specify a table-name attribute on the entity so it still points to the same
table in the database
2. create a new entity the replaces the old one, and comment on that fact
3. implement a service to move data from the old/deprecated entity to the
new one
You'll see this pattern used in a few places. This is kind of the way that users in general have some sort
of hope of being able to update from one revision of OFBiz to another.
How to Send in Your Contributions (or how to

create and apply patches)
The first step is to create an account for yourself on the JIRA issue tracker and then create a new issue.
Describe the contribution that you are making: are you fixing a bug, improving an existing feature, or
creating a new feature? Please write as detailed a description as you can and attach screenshots if
possible of what you've done. OFBIZ is a huge project, and what may be obvious to you might not be to
someone else, even a committer who is familiar with the project.
Then, send in a patch file. This is a file which will describe all the differences between your modified code
and the code in the OFBiz Subversion repository. You can create a patch file by using a command like
this:
$ svn diff applications/product > product.diff
will give us a patch file for all your changes in the applications/product sub-directory and save it as
product.diff.
If you have added new files, then use the "add" command first, then make the diff
$ svn add applications/product/<my-file>
$ svn diff applications/product > product.diff
You can also specify the exact files that you'd wish to include in your patch file, in case there are files that
you have modified but do not wish to submit. For example, you can use
$ svn status applications/product
to see which files have been modified (they start with an "M") or added (which start with a "?").
Then do:
$ svn diff applications/product/entity/

applications/product/script/org/ofbiz/shipment/shipment/ShipmentServices.
xml > product-shipment.diff
if you only want to make a patch file of the entity/ sub-directory and the ShipmentServices.xml file.
For consistency, please make your patch files from the OFBIZ_HOME directory (usually ofbiz/)
and with relative file paths. Your patch file should have file names like:
applications/party/widget/partymgr/PartyScreens.xml
framework/webtools/config/WebtoolsErrorUiLabels.properties
and should not have file names like:
C:\myfiles\ofbiz\applications\party\widget\partymgr\PartyScreens.xml
Make sure that the from/current revision of your local sandbox (checkout) is the current
revision, or a very recent one, from the OFBiz SVN repository. The local revision can be checked
by doing:
$ svn info
To make sure you have the most recent revision always do an SVN update before doing the patch with
svn diff, something like this:
$ svn up
This must always be done before submitting a patch otherwise the patch just won't work. If your local
sandbox is checked out from a separate SVN repository following the vendor branch pattern instead of
directly from the OFBiz SVN, then you should do a vendor branch update, merge, and then local update
in your sandbox before doing the svn diff to create the patch.
Next upload your patch file to your JIRA issue. Please use .patch as extension, some tools use extensions
and this facilitates commiters works.
Finally, if there are several patch files already on an issue, please write a comment about which file
should be used. A best practice is also to keep the same filename if a patch file is updated. Jira will take
care of that and will keep (better for history) but gray deprecated files with the same filename. It's easier
for commiter to see at 1st glance which file to use. You can read in 1st comment below what may happen
when not using the same filename.
When a Jira issue is totaly resolved, we prefer to close the issue than to put it as resolved. There are
some cases where there is a tentative resolution and you don't want to close the case because you want
the reporter or someone to review and test the fix to make sure it was what was intended. If it is a
simpler issue and especially if you are the reporter, then it is best to just close it right away rather than
coming back to it later to close.
Why is it Taking So Long to Get My Patch into

OFBiz?
The first thing to remember is that in order for something to get done an individual or group must have
sufficient ability and time to do it. There are no paid OFBiz committers, everyone works on a volunteer
basis. This is a natural side effect of OFBiz being a community-driven project rather than "commercial
open source".
When someone submits a patch they are asking for someone in the group of committers to do something
for free. Sometimes because of the volume of patches it is overlooked and then with a constant stream
of new issues, complaints, questions, etc it may be a long time (if ever) before someone gets back to it.
Most unfortunately there aren't any committers that can work on contributing to OFBiz full-time because
so far there are no committers that don't need to also earn a living. Most committers work with OFBiz in
their day job, and because of the size and complexity of the project so far that seems to be the only way
someone even can consistently contribute to OFBiz. That doesn't mean they are paid to work on your
issue though, unless you and they get lucky and it happens to be related to a paid client objective.
If you REALLY want your patch in, you can get it in. If you want it in, your job is to help the committers
get it in. You can recruit others on the mailing lists to review and test your patch. This is really important,
because OFBiz is fairly complex and many patches break rule #1, which is in short, "first do no harm".
In other words, do break stuff that already exists that other people implemented, and that other people
are using.
There is also another option... as mentioned above OFBiz is unfunded and every committer has an
employer of some sort, often a handful of clients. This would explain why things are getting committed
all the time, even though sometimes the volume of patches getting reviewed and committed is pretty low.
If committers are lucky then they get to work on stuff that goes back into OFBiz, and that is ONLY reason
that most of the functionality in OFBiz exists at all, especially in the applications (most of the framework,
on the other hand, was not ever sponsored). Some people see this as unfair. Others see it as a great
stroke of luck that they can take advantage of.
If this isn't working for you, then consider getting more involved with OFBiz or somehow making it
possible for others to get more involved with OFBiz. There are many ways you can help, even without
becoming a committer yourself. There are the exact same things you can do in order to become a
committer if you do enough of them, but of course you can do all of these without any longer term
commitment or hoops to jump through. You don't even have to get a committer or PMC member to do
anything in order to do these things!
1. Subscribe to the dev mailing list, try to read the majority of the messages, and participate in
discussions there
2. Review and comment on issues in the Jira issue tracker
3. Apply patches from Jira locally and test them and comment on the results
4. Create patches to fix issues reported in Jira
5. Get to know OFBiz and submit patches to fix problems or annoyances you find
6. Follow all of the rest of the advice in this document
How Do I Become a Committer Myself?
If you're interested in becoming a committer, that's great! We would love to have you and the whole
community will really appreciate your help.
Being a committer can be a great help to your employer and/or clients. It can also be a great asset in
your personal and career growth. There is a guarantee that in the course of your activities you will learn
and grow. You'll learn about building enterprise applications, both the technical and business sides of
them. You'll also learn a lot about working with other people, especially working with other people
remotely.
For more information and to get started see the Committers Roles and Responsibilities page.

OFBiz USER GUIDE PDF

Încărcat de

Informații document

Titlu original

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

OFBiz USER GUIDE PDF

Încărcat de

Drepturi de autor:

Formate disponibile

C:\ofbiz> c:\ant\bin\ant run-install

Now open up a browser and type into the navigation bar:

$ java -jar ofbiz.jar -pos

First, go into your OFBiz directory and take a look inside:

o OFBiz is built around a components-based architecture, which means each application is

Now let's go inside framework/ and take a look:

[sichen@localhost ofbiz_5010]$ cd framework/

Now go back and take a look at the applications themselves:

Now let's go inside an application and see what it looks like:

[sichen@localhost applications]$ cd product/

[si@localhost product]$ ls -l entitydef/

[si@localhost product]$ ls -l webapp/

[si@localhost product]$ ls -l webapp/catalog/

[si@localhost product]$ ls -l webapp/catalog/WEB-INF/

[si@localhost product]$ ls -l webapp/catalog/product/

[si@localhost product]$ ls -l widget/

Now let's take a look at what's in a widgets directory:

[si@localhost product]$ ls -l widget/catalog/

Throughout this tutorial, click on any image to enlarge it.

Httpd started on port: 9989

Here is an example of how to get values from fields:

bsh % print(me.getString("firstName") + " " + me.get("lastName"));

bsh % me.set("memberId", "11111");

bsh % me2 = delegator.findByPrimaryKeyCache("Person",

We call services through an object (usually) called dispatcher, which is of a sub-class of

esh % result = dispatcher.runSync("createPerson",

bsh % result = dispatcher.runSync("updatePerson", UtilMisc.toMap("partyId",

Target exception: org.ofbiz.service.ServiceAuthException: User

org.ofbiz.service.ServiceAuthException: User authorization is required for

result = dispatcher.runSync("updatePerson", UtilMisc.toMap("partyId",

Cannot nest output folder "hot-deploy/crmsfa/src" inside "ofbiz/"

强烈推荐想快速入门 OFBiz 的开发人员，先照着这几个例子做几遍。

First, each web.xml file in the hello_/webapp/hello_/WEB-INF/ must be changed so that:

<fileset dir="../../base/lib" includes="*.jar"/>

<fileset dir="../../framework/base/lib" includes="*.jar"/>

<?xml version="1.0" encoding="UTF-8"?>

o That we have a component named "hello1"

<?xml version="1.0" encoding="UTF-8" ?>

<handler name="java" type="request"

<handler name="ftl" type="view"

<handler name="http" type="view"

Now we are ready. Let's run our first application:

One last thing to try, type in:

<%@ page import="org.ofbiz.base.util.*" %>

<% String errorMsg = (String) request.getAttribute("_ERROR_MESSAGE_"); %>

This is the final content of your webapp directory:

Click to see the complete files for this application.

Extending your web app with screen‐widget, decorator, and

Throughout this tutorial, click on any image to enlarge it.

I also created an entry for it in controller.xml.

Click to see the files created in this tutorial.

org.ofbiz.entity.GenericEntityException: Helper name not found for entity

<entity-resource type="model" reader-name="main" loader="main"

5336 (main) [ UtilXml.java:242:DEBUG] XML Read 0.0070s:

When you go into webtools, you will see the entities:

<entity-resource type="data" reader-name="seed" loader="main"

Now our application is done. Here is the guestbook page:

and here is the hobbies page:

Click to see the list of files for this application.

17149 (main) [ DatabaseUtil.java:277:WARN ] Entity "HelloPerson" has