Page History

Introduction

The Open For Business Project: General Entity Overview

Written By: David E. Jones, jonesde@ofbiz.org

Status: This document is an early attempt to organize the data corresponding to the various components of the overall system.  Some parts are much more complete and thought out than others. Please send me feed back on any omissions or errors.

Table of Contents

• Introduction
• Extensibility Pattern
• Deprecated Entities
• Common
  • common.geo
  • common.period
  • common.status
  • common.uom
• Party
  • party.party
• Product
  • product.product
  • product.category
  • product.feature
  • product.cost
  • product.price
  • product.inventory
  • product.storage
  • product.supplier
• Security
  • security.login
  • security.securitygroup

Introduction

The purpose of this document is to describe the Entities OFBiz entities in various components and their design. A brief overview of each component will be presented which will include a description of the entities in the component and their relations to other entities.

There are some files that go along with the definitions of these entities. These files are located in the "entitydef" directory of each components. The most important file is generally named something like entitymodel*.xml which contain the XML definitions for all of the entities in the project'entitydef' folder in the datamodel component for the base OFBiz components. For special purpose components the entity definitions are in the 'entitydef' folder of the particular component. For an explanation of what these entity types are and how they are used, see the Extensibility Pattern section of this document.

Another important set of files is in the "data" directory folder of each component. These are XML Entity Engine Import files that contain seed and demo data including various entity types for related to the various entities in the data model. For an explanation of what these entity types are and how they are used, see the Extensibility Pattern section of this document.

Extensibility Pattern

There is one pattern that you will see repeated often in this the OFBiz data model that warrants some explanation. This pattern is used to make the data model more flexible and eliminate a great many tables that might otherwise have to exist. It aids in the conceptualization of the use of an entity that follows this pattern. It also provides a method for run-time extensibility of the entities that use this pattern.

For a given Entity there are 3 or 4 related entities that are used to implement this pattern. These are:

• EntityClass (optional),
• EntityType, 
• EntityAttribute,

...

• and 
• EntityTypeAttr.

Each Entity instance can have one or more types which are described by EntityType. If an Entity can have multiple types the EntityClass, or Entity Classification entity is used to implement the many-to-many relation between Entity and EntityType. Otherwise no EntityClass is necessary and Entity will have an entityTypeId field.

EntityType

EntityType is used to describe an Entity. A given EntityType can inherit features from a parent EntityType if one is specified in the parentTypeId field of a given EntityType instance. If a table is associated with a given EntityType instance that has the same name as the entityTypeId field value then the hasTable field should have the value 'Y', otherwise it should have the value 'N'. A description field is provided for a short description of an EntityType instance.

EntityAttribute

EntityAttribute is used to store instances of name-value pair attributes for a given Entity instance. An attribute can be used in place of a column on the Entity table, especially when the attribute does not apply to all types of Entities. Attributes can also be used ad-hoc for any name-value pair information that applies to a given Entity instance. If many attributes apply to a given EntityType it may be best to create a separate entity to hold those attributes, and have that entity be associated with the EntityType instance by naming it the same as the entityTypeId and setting the hasTable field to 'Y' on the EntityType instance. This will be faster than repeatedly querying a collection of attributes for a given Entity instance.

EntityTypeAttr

EntityTypeAttr is used to specify which attributes should exist for an Entity instance that corresponds to a given entityTypeId. The entityTypeId and name field combinations are listed to specify this. For example, the EntityType with entityTypeId 'BOX' should always have attributes named 'HEIGHT', 'WIDTH', 'DEPTH', and 'COLOR', so an instance of EntityTypeAttr will exist for each of these attributes.

...

Deprecated Entities

Entities prefixed with 'old' "Old" are deprecated.  The underlying table names remain unchanged by explicitly specifying the corresponding table name (see the table-name attribute in the entity definition).

When changing an entity significantly, and especially when changing the primary key, always deprecate the existing entity and create a new one so that an upgrade path for existing databases is possible. To facilitate this in addition to deprecating the old entity (prefixing with "oldOld") and defining the new one you should always create a service to move data from the old entity to the new one. The service doesn't have to figure out when to run itself (which is tough to figure out and generally not reliable), and generally should be made to be run manually.

When deprecating an entity make sure to search for all references to that entity and change them to use the new entity. At the end of the process the only reference to the deprecated entity, and with the "Old" prefix of course, should be the migration service.

When changing the name of a field, or deprecating and replacing a field that does not require deprecation of the entire entity, then follow the same pattern leaving the old field there: a "old" prefix added to the field name, change the original first letter to upper case, and specify the column-name for the field so it is the same as the original field name. For example if you are changing the "uomId" field to a new name then change the field name to "oldUomId" and specify a column-name of "UOM_ID". Just as when replacing and entity, make sure to write a service to move the data from the old field to the new one.

Whenever doing any of these sorts of changes that require additional steps to update a production server, ALWAYS add an entry on this page: Revisions Requiring Data Migration - upgrade ofbiz

Packages

Common

The Common package is meant to contain entities that are for general use and may be used by entities in many other packages.

...

SecurityGroup SecurityPermission SecurityGroupPermission UserLoginSecurityGroup

InventoryItem

The InventoryItem entity records items of a Product in stock in a Facility at a FacilityLocation.