The Open For Business Project SourceForge Logo

The Open For Business Project: CommonApp Entity Overview

Written By: David E. Jones, [email protected]
Last Updated: July 12, 2001

NOTE: This document will be added to as parts of the data model progress.

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


The CommonApp module is where all of the Common Application Components from the ofbiz architecture diagram are located. The Common Application Components are software components that are shared by all or many of the vertical applications in the project. For example, Products and LoginUsers are defined in the CommonApp module but may be used in various vertical applications such as e-commerce, inventory management, accounting, sales and purchase order management, and so forth.

The purpose of this document is to describe the Common Application 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 ofbiz/commonapp/entitydef directory. The most important file is entitymodel.xml which contains the XML definitions for all of the entities in the project.

Another file in the ofbiz/commonapp/db directory named datamodel-data.sql is a series of SQL insert statements which define various entity types for 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 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 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 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 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.

There are variations on this pattern for certain entities, but this description is generally applicable in this data model. Note that the default types for the data model are defined in ofbiz/commonapp/entitydef/datamodel-data.sql.


Common


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

common.geo  

Geo GeoType GeoAssoc GeoAssocType 

common.period  

PeriodType StandardTimePeriod 

common.status  

Status StatusType 

common.uom  

Uom UomType UomConversion


Party


The Party package is meant to contain entities related to the Party entity. There are many types of parties, and a lot of data that is associated with a party or with parties, and that data is defined in this package. Parties include persons, organizations, and so forth.

party.party  

Party PartyClassification PartyClassificationType PartyType PartyAttribute PartyTypeAttr PartyRole RoleType RoleTypeAttr PartyRelationship PriorityType PartyRelationshipType Customer PartyDataObject Person

Product



The Product package is meant to contain entities related to the Product entity. There are many types of products, and a lot of data that is associated with a product or with products, and that data is defined in this package. A Product can be a good or a service, and each may have various subtypes. Some related data that is fairly central to Product definitions includes features and categories. The Category package allows products to be organized, and the Feature package describes details of a product that may be used for pricing or in a parametric product search.

The Product package also contains information about serialized and non-serialized inventory items, and the storage of inventory in facilities which can be warehouses, stores, or whatever. There is a package for Product cost estimation, and another for Product price calculation. In addition there is a package for Product supplier related information to keep track of where a product might come from and to rate and put a priority on different suppliers of the same product.

product.product  

The Product entity contains general information about a product, whatever type of product it is. Product implements the Extensibility Pattern, and can have multiple types, using the Product, ProductClass, ProductType, ProductAttribute, and ProductTypeAttr entities. 

When a Product is of the type GOOD (as opposed to SERVICE) then it generally has identifications associated with it such as a SKU, an ISBN, a SKU or catalog ID from manufacturer or distributor, and so forth. These are stored in the GoodIdentification entity and the type of good id is defined by the GoodIdentificationType entity.

The ProductAssoc entity implements an association between products. The type of association is defined by the corresponding ProductAssocType entity. ProductAssoc partially implements the Extensibility Pattern by providing a type, but does not have attributes at the moment. ProductAssoc entities can be used to specify that a certain product is deprecated by another product, or can be substitued for another product. A Product can also be a 'dummy' product and simply be a collection of other products that are components of this product, or the product could be a special offer or marketing package used to promote and sell various products as a single product. Many other potential associations can be used between products. Marketing concepts such as up-sells and cross-sells can also be implemented using ProductAssoc entities.

The ProductDataObject entity is used to implement the many to many join between a Product and a DataObject. The DataObject entity is part of the Content package and is used to store text or images or other general content as a content management package. To simplify the data model the Product entity also has fields for a long description and URLs to images, but these are optional and larger organizations will want to use the content management features to control this sort of content.

product.category  

ProductCategory contains information about categories of products, and can be used to organize products for cataloging, marketing, analyis, and other purposes. ProductCategory implements the Extensibility Pattern, and can have multiple types, using the ProductCategory, ProductCategoryClass, ProductCategoryType, ProductCategoryAttribute, and ProductCategoryTypeAttr entities. 

A ProductCategory has a many to many relation with Product meaning that a Product can belong to many ProductCategories and a ProductCategory can contain many Products. This many to many relation is joined using the ProductCategoryMember entity which contains a reference to a Product and a ProductCategory.

A ProductCategory can be related to other product categories in a loose hierarchical structure. When I say loose I mean that it differs from a normal hierarchy in that it can have multiple parents, making it really a graph, but we still use terminology that comes from an hierarchical organization. This many to many relation is joined using the ProductCategoryRollup entity. An alternative to this is to implement a true hierarchy by removing or not using the ProductCategoryRollup entity and simply using a field in the ProductCategory entity to specify a reference to the ParentProductCategory. This can be done with the current data model by using the primaryParentCategoryId field as a reference to the only parent category.

product.feature  

ProductFeature ProductFeatureType ProductFeatureCategory ProductFeatureAppl ProductFeatureApplType ProductFeatureIactn ProductFeatureIactnType FeatureDataObject 

product.cost  

CostComponent CostComponentType CostComponentAttribute CostComponentTypeAttr 

product.price  

PriceComponent PriceComponentType PriceComponentAttribute PriceComponentTypeAttr QuantityBreak OrderValueBreak SaleType 

product.inventory  

InventoryItem InventoryItemType InventoryItemAttribute InventoryItemTypeAttr PhysicalInventory InventoryItemVariance VarianceReason ItemVarianceAcctgTrans Lot 

product.storage  

Container ContainerType Facility FacilityType FacilityAttribute FacilityTypeAttr FacilityContactMechanism PartyFacility FacilityRoleType 

product.supplier  

ReorderGuideline SupplierProduct SupplierRatingType SupplierPrefOrder MarketInterest


Security


The Security package contains entities related to controlling access to various parts of applications that use the CommonApp data model. The Login package has a UserLogin entity which contains the usernames and passwords of all users on the system and which is optionally related to a Party entity instance. The Login package also has an entity which keeps a history of logins into the system.

The SecurityGroup package contains entities used to map SecurityPermissions to UserLogins. It goes this by mapping a UserLogin to a SecurityGroup and then mapping the SecurityGroup to a SecurityPermission. In this manner complex security definitions can be shared efficiently.

security.login  

UserLogin LoginAccountHistory 

security.securitygroup  

SecurityGroup SecurityPermission SecurityGroupPermission UserLoginSecurityGroup