The purpose of this document is to define a set of rules to clarify and improve
the configuration and customisation process of the ERP5 open source ERP in
commercial projects.
Table of Contents
Purpose and Scope¶
This document covers organisational approach to customisation.
It does not contain any information to improve technical skills of consultants.
For technical skills, please refer to the
ERP5 Implementation Process. This document is meant to be read by Nexedi
developers and by selected Nexedi partners.
This document is meant to be read by Nexedi developers and by selected Nexedi
partners. This document must not be distributed outside Nexedi without prior
explicit permission of Nexedi CEO.
Abstract Rules¶
ERP5 configuration and customisation is based on business templates. This Chapter
provides some basic abstract rules to guide consultants in their choice.
Update Frequency¶
The update frequency of ERP5 components (business templates and products) is a
difficult question and depends on the situation:
- Are we in development phase, in production phase, in a combination of both?
- Are we extending ERP5 or only using standard ERP5 components?
We have experienced multiple cases in which the update frequency was wrongly selected:
-
During configuration. A major service company has decided to use ZSQLCatalog.
Following the corporate policy, they took a given version of the component and
never upgraded it during 1 year. They fixed many bugs which they never
contributed back. After 1 year, they were using a very different ZSQLCatalog
which was incompatible with the main branch. They did not benefit from
tremendous improvements made to the main branch nor from stability fixes.
We experienced similar behaviour from another major service company which did
the same with an open source content management system and did not upgrade it
during 2 years. In the end, the project was a technical failure.
-
During configuration. A team of 4 engineers was committing every day their
configuration as a business template and updating the configuration from the
3 others. This took nearly 25% of their daily work. Configuration was
progressing very slowly. It was then decided to configure the system with a
shared configuration server.
-
During test. A major ERP5 project was updating daily a development server into
a test server. Customer was experiencing recurrent bugs (ex. the bug of one
day was fixed, a new bug was created). Lack of automated test preventing from
making sure that upgrade would not introduce bugs which were already fixed.
-
During production. An independent ERP5 user has refused to upgrade its system
during 1 year, following the rules learnt in a very large IT service company.
He did not contribute himself to the extension of ERP5 main branch. After one
year, upgrade to the main branch became very complex, requiring to migrate data.
All experiences tend to prove that the choice of the update frequency must be a
well understood and pragmatical choice and may be different for every environment.
These experiences also show that distributed development, which is perfect to
maintain the stable branch of ERP5 products and business templates, may not always
apply to team configuration.
Rule: During the configuration phase of a project, upgrade products
and business template not too often, not too little. Every day is too often,
every 3 months is too little. Every week or month is OK.
Rationale: If one updates every day, then he spends much time on updating and little time
on configuring. If one updates every 3 months, he spends much time on fixing
bugs which are already fixed, and less time on configuring.
Rule: During the production phase of a project, only proceed to
selective and corrective updates.
Rationale: updating a production site can be very risky because unexpected
bugs resulting from the incompatibility between the custom configuration and
the generic ERP5 components may appear. Upgrade should normally be considered
as a project itself.
Rule: In a phase by phase project where production starts before the
end of configuration, combine longer time to time updates (ex. 1 or 2 months)
with automated testing to make sure upgrades do not break the existing system.
Rationale: it might be acceptable to block users every month as long as
upgrades do not generate system inconsistencies. To prevent system
inconsistencies, wider test coverage is required.
Interactive configuration¶
The notion of update frequency applies to distributed development or configuration.
However, in most cases, the configuration of an ERP5 system is an interactive and
iterative team process based on a shared ERP5 server. Although this is obvious
for most ERP5 developers, we remind it here to prevent any misunderstanding
related the notion of update frequency. The update frequency applies to the
products and business templates installed on the shared server, not to the
configuration itself.
Some projects combine configuration, custom development, generic ERP5 development.
Our recommendation is to:
- use a shared server approach for configuration and integration;
- use a distributed development generic ERP5 development (see bellow);
- use either a shared server approach or a distributed development approach for customer specific development, depending on the project size, parallelism and complexity.
Rule: Use a shared Zope server for interactive collaborative configuration.
Rationale: In a situation where configuration consists in parallel tasks with
strong interaction (ex. order and packing list), it is easier for multiple
developers to work in the same room (or chat) and on the same system rather
than try to implement a distributed configuration process with regular updates.
Customisation Management¶
The two worse situations during the customisation of ERP5 consist occur whenever one:
- does not know what was changed to the main ERP5 branch;
- implements bug fixes or extensions to ERP5 which are not integrated to the
main branch and become incompatible with future evolutions of ERP5 main branch
Preventing these situations is quite easy by segregating changes and contributing to ERP5.
Rule: Consider how to integrate changes or fix bugs in the official
version rather than patching locally, by discussing changes with corresponding
maintainers.
Rationale: the more customisation, the more complex upgrade becomes (cost, time,
stability).
Rule: Segregate local changes which cannot be merged with the official
version explicitly and clearly.
Rationale: knowing precisely differences between the standard ERP5 products
and business templates and the custom configuration simplifies maintenance
and upgrade.
Segregation¶
This chapter discusses segregation techniques in ERP5. The purpose of
segregation is to clarify the origin of each software component in a way which
make upgrade as well as contribution to the core of ERP5 much easier.
Components¶
An ERP5 system is built out of 4 types of components:
- Business Templates¶
- ERP5 Products
- Zope and Zope products
- Operating system, database, binaries, etc. provided by ERP5 LiveCD
For every type of component, different segregation rules apply.
Business Templates¶
During the configuration process, two types of business templates must be created
by the consultant:
-
patch business templates which include all changes to the generic business
templates (ex. accounting, apparel, etc.) and may overwrite objects provided by
other business templates.
-
customer specific business templates (ex. a new PDF form) which provide new
objects but do not overwrite objects provided by other business templates.
Patch business templates allow for knowing which changes may eventually be
contributed back to ERP5 core. They also provide a way to assess the risk
updates of official generic business templates.
Customer specific business templates allow for implementing version control and
unit testing of customer configuration projects. They can be used to assess
which parts of a customer project may eventually contributed back into a new "vertical"
business template (ex. ERP5 Apparel).
Rule: install generic templates for generic functionalities (ex. erp5_trade),
use patch templates (ex. erp5_trade_patch) for local customisation, use custom
templates (ex. mycustomer_newapp) for customer specific extensions and
application development.
Rationale: the use of patch business templates allows for clarifying changes
to the ERP5 base and easing the contribution of changes back in the core of
ERP5 official branch. The use of custom templates allows for easing the
maintenance of customer specific development and extensions. It is also
necessary for automated tests ran on a test server.
Products¶¶
Most ERP5 projects do not need the creation of a custom Zope Product. The
exceptions to this rule are projects which consist in a sense in creating a
new vertical application or projects which involve a lot of interfaces and
equire new tools. It is always a good thing to try to design new Zope products
in such way that they can be contributed to the core of ERP5 and shared with others.
Rule: only create a Zope Product for complex projects which need to
extend many ERP5 standard classes.
Rationale: If a lot of python source code must be developed in classes
(Document, Tool, etc.)
Rule: Try to make new Zope Product as generic as possible to extend the core of ERP5
Rationale: Being the only one to use a Zope Product means higher maintenance costs.
Zope and Zope Products¶
Rule: If there is really no other way, fix Zope bugs or Zope product
bugs in the form of monkey patches and store them in the “patches” directory of
a customer specific product.
Rationale: By knowing which patches were applied to Zope and Zope products,
and keeping those patches in a separate product, upgrade of the LiveCD or of
RPMs is made easier. However, the more patches, the less maintainable the system.
Operating System and Database¶
Rule: if you find a bug, ask for support
Rationale: It is not the responsibility of an ERP5 configuration consultant to
search and fix bugs in Linux or MySQL. Try to circumvent bugs or ask a Nexedi
expert. Ask for an upgrade of the LiveCD or of the RPMs.
ZODB Configuration¶
Most of not all ERP5 configuration is achieved through scripts, forms, workflows,
portal types, actions, etc. stored in the object database of Zope, also known as
ZODB.
Skins¶
Rule: Store all local skins in custom folders (e.g. mycustomer_accounting)
Rationale: Portal skin folders and priorities provide a very simple, flexible,
modular and clear system to override behaviours of existing components.
Portal Types¶
It is a mistake to recreate all portal types with other names for concepts which
already exist and only need to be extended. Therefore the rule of reusing existing
portal types. However, we experienced that it was a mistake for maintenability
using a given portal type (Sale Order) to implement something very similar
(Meeting Request) in a health application. It would have been much easier to
create an ad hoc portal type for that purpose. We therefore recommend to use new
portal types for new concepts.
Rule: Do not create new portal types to override existing portal types
Rationale: if you want to extend a standard portal type (ex. Sale Order), create
a patch business template or a custom business template. Register any changes
you did in that business template.
Rule: Create new portal types to implement new document types
Rationale: It is better to create a new portal type for a concept which does
not exist in ERP5, even if that concept is similar to an existing concept.
Workflows¶
Rule: Use a different id for new workflows
Rationale: Having different workflows is easier to compare them.
Modules¶
Rule: Do not change module id
Rationale: Some stability in the structure of ERP5 is required. Patch business templates can be used to overwrite some module properties.
Rule: Create a new module for new document types with workflow and use case
Rationale: Storing different beasts in the same place is often confusing. The
exception in current ERP5 design is the accounting module. However, the current
accounting configuration is not suitable for a large company where different
accounting transactions follow different workflows and use cases. Multiple
modules would be required.
Rule: Use existing modules for similar document types which follow
same workflow and use case
Rationale: The accounting module in ERP5 shows a typical example of storing
similar documents in the same module. The design is ideal for a small company.
Class and Product Development¶
Document Classes¶
Rule: To extend an existing Document class, create a Document class
with the same name as the class it inherits from
Rationale: ERP5 is designed in such way that any Document class can be overloaded
at runtime by another Document class without any change to the ZODB. This is a
fantastic help for the evolution of existing ERP5 systems. Extension of
document behaviour can be obtainer by creating subclasses of the existing
Document classes.
A common mistake consists in extending a given class in ERP5 (ex. Resource) by
creating a class (ex. MyProjectResource) which includes some additional methods.
Doing this is bad because all portal types and modules which are based on the
Resource class must be redesigned. The right approach is to create a new class
following the same name as the class one wants to override (ex. Resource) and
make it inherit from the original class (ex. Products.ERP5.Document.Resource).
ERP5 design makes all document classes and factories act as if they were part of
the ERP5Type.Document module, even if they were defined elsewhere. This
indirection process allows for easy customisation of any ERP5 class through
portal_classes or through products.
As a consequence, it is forbidden access Document classes directly in ERP5
customisation projects.
Rule: Only use factories to create document class instances (ex.
addResource, newTempResource). Never create instances by calling the
__init__ method directly (ex. Resource())
Rationale: Factories are dynamically generated and use the correct Document
class (in case a Document class has been overriden).
In some cases, it is necessary to create new Document classes which capture
generic behaviours which are not defined in the core ERP5. Creating new classes
must be done very carefully. For example, creating new classes because of pure
presentation differences is likely a mistake and would make a system less
maintainable. However, creating a new class to implement complex indexing
schemes might be acceptable.
Rule: create a new Document class whenever a portal type requires a new
support Document class which does not exist in the official ERP5 and which
requires extra logic (not presentation)
Rationale: Document classes in ERP5 are meant to be quite generic. They can
be shared by multiple portal types. Most of the time, it is useless to create
a new Document class.
Products¶¶
Rule: Refactor document classes into products for large projects which
require distributed development and use many custom classes
Rationale: If a project uses a large collection of classes (ie. more than 10),
it is probably reasonable to create a dedicated product and use a version
control system. For just a few classes in a simple project, it is overkill.
Use business templates instead.
Limitations¶
Deletion of objects or properties¶
The business template system does not support the deletion of objects or properties
setup by other business templates. This leads to some limitations:
-
Whenever updating a generic business template and installing a custom business
template, some portal types end up with “too many and conflicting” workflows.
- Useless modules can not be deleted.
Short Term Solution¶
- Use the state variable of workflows to make sure only a single workflow is used per state variable
- Hide modules by overriding security settings
- Implement a “patch” behaviour in business templates to allow overwriting objects or properties (ie. to allow conflicts).
Future (Z3ERP)¶
The problem of short term solutions is that, although they do the job, they are
based on business templates which conflict each other. This is usually something
to be prevented.
- Use ERP5 subobjects to defined actions, workflow states, transitions, etc.
- Implement a globally layered object file system
Related Articles¶