Apache OFBiz Developer Manual

28 janvier 2020

1. Introduction

Welcome to the Apache OFBiz developer manual. This manual provides information to help with customizing and developing OFBiz. If you are new to OFBiz and interested in learning how to use it, you may want to start with the "Apache OFBiz User Manual".

OFBiz is a large system composed of multiple subsystems. This manual attempts to introduce the overall architecture and high level concepts, followed by a detailed description of each subsystem. In addition, the manual will cover topics necessary for developers including the development environment, APIs, deployment, security, and so on.

1.1. Main systems

OFBiz at its core is a collection of systems:

  • A web server (Apache Tomcat)

  • A web MVC framework for routing and handling requests.

  • An entity engine to define, load and manipulate data.

  • A service engine to define and control business logic.

  • A widget system to draw and interact with a user interface.

On top of the above mentioned core systems, OFBiz provides:

  • A data model shared across most businesses defining things like orders, invoices, general ledgers, customers and so on.

  • A library of services that operate on the above mentioned data model such as "createBillingAccount" or "updateInvoice" and so on.

  • A collection of applications that provide a user interface to allow users to interact with the system. These applications usually operate on the existing data model and service library. Examples include the "Accounting Manager" and "Order Manager".

  • A collection of optional applications called "plugins" that extend basic functionality and is the main way to add custom logic to OFBiz.

1.2. Components

The basic unit in OFBiz is called "component". A component is at a minimum a folder with a file inside of it called "ofbiz-component.xml"

Every application in OFBiz is a component. For example, the order manager is a component, the accounting manager is also a component, and so on.

By convention, OFBiz components have the following main directory structure:

component-name-here/
├── config/              - Properties and translation labels (i18n)
├── data/                - XML data to load into the database
├── entitydef/           - Defined database entities
├── groovyScripts/       - A collection of scripts written in Groovy
├── minilang/            - A collection of scripts written in minilang (deprecated)
├── ofbiz-component.xml  - The OFBiz main component configuration file
├── servicedef           - Defined services.
├── src/
    ├── docs/            - component documentation source
    └── main/java/       - java source code
    └── test/java/       - java unit-tests
├── testdef              - Defined integration-tests
├── webapp               - One or more Java webapps including the control servlet
└── widget               - Screens, forms, menus and other widgets

It is apparent from the above directory structure that each OFBiz component is in fact a full application as it contains entities, data, services, user interface, routing, tests, and business logic.

Both core OFBiz applications as well as plugins are nothing more than components. The only difference is that core applications reside in the "applications" folder whereas plugins reside in the "plugins" folder; also OFBiz does not ship with plugins by default.

1.3. Example workflow

Many basic concepts were explained so far. An example would help in putting all of these concepts together to understand the bigger picture. Let us take an example where a user opens a web browser and enters a certain URL and hits the enter key. What happens? It turns out answering this question is not quite simple because lots of things occur the moment the user hits "enter".

To try to explain what happens, take a look at the below diagram. Do not worry if it is not fully understandable, we will go through most of it in our example.

ofbiz architecture

1.3.1. User enters URL

In the first step in our example, the user enters the following URL:

https://localhost:8443/accounting/control/findInvoices

If we break down this URL, we identify the following parts:

  • localhost: Name of the server in which OFBiz is running

  • 8443: Default https port for OFBiz

  • accounting: web application name. A web application is something which is defined inside a component

  • control: Tells OFBiz to transfer routing to the control servlet

  • findInvoices: request name inside the control servlet

1.3.2. Control servlet takes over

The Java Servlet Container (tomcat) re-routes incoming requests through web.xml to a special OFBiz servlet called the control servlet. The control servlet for each OFBiz component is defined in controller.xml under the webapp folder.

The main configuration for routing happens in controller.xml. The purpose of this file is to map requests to responses.

Request Map

A request in the control servlet might contain the following information:

  • Define communication protocol (http or https) as well as whether authentication is required.

  • Fire up an event which could be either a piece of code (like a script) or a service.

  • Define a response to the request. A response could either be another request or a view map.

So in this example, the findInvoices request is mapped to a findInvoices view.

View Map

A view map maps a view name to a certain view-type and a certain location.

View types can be one of:

  • screen: A screen widget which translates to normal HTML.

  • screenfop: A PDF screen designed with Apache FOP based constructs.

  • screencsv: A comma separated value output report.

  • screenxml: An XML document.

  • simple-content; A special MIME content type (like binary files).

  • ftl: An HTML document generated directly from a FreeMarker template.

  • screenxls: An Excel spreadsheet.

In the findInvoices example, the view-map type is a normal screen which is mapped to the screen: component://accounting/widget/InvoiceScreens.xml#FindInvoices

1.3.3. Widget rendered

Once the screen location is identified and retrieved from the previous step, the OFBiz widget system starts to translate the XML definition of the screen to actual HTML output.

A screen is a collection of many different things and can include:

  • Other screens

  • Decorator screens

  • Conditional logic for hiding / showing parts of the screen

  • data preparation directives in the <action> tag

  • Forms

  • Menus

  • Trees

  • Platform specific code (like FreeMarker for HTML output)

  • Others (portals, images labels etc …​)

Continuing the example, the FindInvoices screen contains many details including two forms. One form is for entering invoice search fields and the other form displays search results.

1.4. Gestion de la documentation

Comment la documentation est organisé, avec quels outils est-elle réalisé, quels sont les conventions et toutes les autres questions concernant la gestion de la document et son élaboration sont traité dans un document dédié.

cf documentation_guidelines

Il existe plusieurs documentations, chacune avec un objectif ou un lectorat cible, pour l’instant chacune est représenté par un fichier dans le répertoire racine .

2. Web Framework

Unresolved directive in <stdin> - include::../../framework/webapp/src/docs/asciidoc/webapp.adoc[leveloffset=+1]

2.1. Control Servlet

2.1.1. Requests

2.1.2. Views

3. Entity Engine

3.1. Entities

3.1.1. Standard Entities

3.1.2. View Entities

3.1.3. Extended Entities

3.1.4. Dynamic View Entities

3.2. XML Data

3.3. Entity engine configuration

3.4. Supported databases

4. Service Engine

4.1. Declaration and Implementation

4.2. Supported languages

4.3. Transaction management

4.4. Web services

5. Widget System

5.1. Screen Widget

5.1.1. Decoration Pattern

5.2. Form Widget 2

5.3. Menu Widget

5.4. Tree Widget

5.5. Portal Widget

5.6. Platform Specific Code

Unresolved directive in <stdin> - include::../../plugins/vuejsPortal/src/docs/asciidoc/FrontJsPortal_fr.adoc[leveloffset=+1]

6. Core APIs

7. Development environment

7.1. Setup your environment

7.1.1. Java SE

7.1.2. IDE

Eclipse
Intellij Idea

pour le hotswap, il faut importer (menu file project structure libraries clicker sur plus pour ajouter ofbiz-framework/build/libs/ofbiz.jar tous les modules (Ctrl A)

7.1.3. Database

Unresolved directive in <stdin> - include::../../plugins/vuejsPortal/src/docs/asciidoc/webhelp_example_fr.adoc[leveloffset=+2]

7.2. Web tools

Unresolved directive in <stdin> - include::../../plugins/example/src/docs/asciidoc/example_fr.adoc[leveloffset=+2]

8. Testing

8.1. Unit Tests

8.2. Integration Tests

8.3. UI Tests

Il existe un projet dédié "OFBiz® Selenium-WebDriver" (OfbSwd) dont le rôle est exclusivement les tests via l’interface utilisateur.

Cela couvre, aussi bien les tests unitaires de l’interface utilisateur que des tests de use case métier.

Pour plus de détail se référer à la documentation de ce projet

9. Deployment

Unresolved directive in <stdin> - include::../../framework/security/src/docs/asciidoc/security.adoc[leveloffset=+1]

10. Appendices

Unresolved directive in <stdin> - include::../../framework/minilang/docs/asciidoc/minilang-to-groovy-manual.adoc[leveloffset=+1]