Hyper Open Edge Cloud

Guideline Project Implemention Rules

[out-of-date] Please use individual guidelines.
  • Last Update:2017-03-27
  • Version:009
  • Language:en

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