Most Powerful Open Source ERP

ERP5 Guideline Module Creation

Table of Contents

Introduction

Modules are one of the core components of ERP5 and usually the ones most development in ERP5 focusses around. It is therefore important that a clear set of conventions are maintained ensuring the modules are created or extended in a consistent and portable way.

Recommendation

#

Do Not Mix Up Description And Comments

The meaning of those 2 properties is different. "Description" should be used to enter a short (one or two sentences) description of a document. "Comments" should be used to enter miscellaneous information concerning the document. All the information that can not take place in any other field or property should be considered as "comment".
Comments should take place in the « right »group of a form as a small text area field. Description should take place in the « center »group as a large text area field.

#

Favor simulation_state Or validation_state For Workflow State

Always prefer simulation_state or validation_state for "workflow state variable"

simulation_state and validation_state can be searched using portal_catalog. It's preferred to use validation_state for documents with a validation cycle and simulation_state for movements and deliveries. Note that it's also important that 2 workflows with the same state variable are not used for one document type. If you have to worklows with simulation_state, document accessors like getSimulationState will not be able to determine which workflow actually sets the simulation_state.

#

First Level Portal Types Should Have A Validation Workflow

Every portal type used as first level document in a module should be associated to a "validation" workflow.

The life cycle of all main documents is defined by a workflow in ERP5. Security in ERP5 is also workflow based.

#

Listbox Only Tabs Should Have A Read Only Title In Center Group

If a view only contains a listbox, a read only "title" field should be shown in the "center" group.

#

The Default Dialog Should Be Used For All Transitions

#

The Listbox Method Should Be Defined As SearchFolder To View Modules

"List Method" should usually be defined as "searchFolder" for listboxes used to view modules.

searchFolder allows to show the content of a folder (module) efficiently by using the ERP5 SQL Catalog. The method used to display documents in a module must use SQL for scalability.

#

Unset Acquire Local Roles On Document Portal Type Configuration If Applicable

If the type of document should not acquire local roles from the parent documents (and modules), uncheck the "Acquire Local Roles" on this portal type configuration.

If the security of sub-document is different, you usually don't want to acquire all roles from the parent. For example, this is the case for Assignment documents, a user can be assigned some person documents, but we don't want this user to open assignment which are physically contained in this person.

#

Use Activities For Heavy Computations

Use activities to do heavy calculations in the background.

To have a responsive system, CMFActivity system should be used to defer execution heavy tasks. Indexing and simulation are done as activities.

#

Workflows Should Define Worklists

Every workflow should define several worklists.

Worklists have to be configured so that a user should just have a look to his "my favourites" menu to know what he has to do in ERP5. The order of the worklist has to be defined according to the lifecycle of the related documents. It is also important to use security correctly, for a validation_workflow if you make a worklist of all states in draft state that have to be validated by the Assignee, specify Assignee in the "Role(s)" guard and add &local_roles=Assignee in the URL. Also, whenever it makes sense, worklists names should describe what the user have to do (good example: "Documents to validate"), and not what documents are selected (bad example: "Documents in draft state"). We usually create one worklist for each step in the workflow.

Rule

#

A Document Form Uses The form_view Page Template

The page template used is 'form_view'

#

A Fast Input Must Use object_fast_input Action

Never configure a fast input action as object_exchange action category, use object_fast_input action category

#

A Validation Workflow Must Have A Delete State And Action

All "validation" workflows must define "Deleted" state and "delete_action" transition.

In ERP5, deleting a document is part of the life cycle of the document. Security should be configured so that only managers can view documents in "Deleted" state. That means, for a common end user, deletion of documents in ERP5 should be seen as "physical" deletion. The "delete_action" must be configured as follow: "Trigger type" must be set to "Initiated by user action", "Name (formatted)" must remain empty, so that this workflow action is not shown in view mode actions. You can specify a guard if needed.As usual, delete_action transition should not have a destination state ("remain in state") and have the "delete" transition as "script after". This "delete" action will have "Trigger Type" "Initiated by WorkflowMethod" and destination state "deleted".

#

Add Column Portal Type If Listbox Contains Multiple Types

Always display the translated_portal_type of documents in the listbox of a module if this module can contain different portal types.

If a listbox in ERP5 is supposed to display objects having different portal types, then a portal type column is needed in the listbox to show this information. What should be displayed is always the "translated_portal_type" so that the forms can be automatically localised.

#

Add Dates In Listbox As Editable Date-Time Field

When displaying a date in a listbox, always configure a specific listbox_date editable Date-Time field in the form.

This allows that the date is displayed in the listbox according to the user date format preference. In ERP5, the most used searchable dates are delivery.start_date and delivery.stop_date. Using these dates in a listbox allows to do some filtering by dates. The column must be named "delivery.start_date", and the editable field must have id "delivery_start_date"

#

Add Viewable Fields To Listbox More Columns

Define in the 'More Column' fields all the properties that an user will be able to display for a main listbox of a module.

The user has to be able to select which columns he wants to see in order to view the content of a module. The More columns field is also used in order to generate a default search dialog on a module. This field has to be defined only for listboxes used in list mode (not used for listboxes inside view forms). Include all properties that can be useful, like creation date, modification date, creator ...

#

Always Provide Portal Type Description

The description is important to explain what the module consists of. You should for example describe what are the documents contained in the module.

#

Configuration And Project Business Templates Must Include Roles For Group, Site And Function

Project specific BT or configuration BT will contains roles for portal types based on some group, site and function categories that will have to be included in this (or another) specific BT.

In ERP5 Security model, security is splitted in two parts, one is to have 5 generic roles, and to use workflows to define security for thoses 5 generic roles (and in some cases also Owner or Anonymous roles), the second part of security definition is to define the mapping between specific business rules based on documents categories or user assignments ( usually group, site and function ) and those roles.

#

Declare Fast Input As Hidden Content Type

If you plan to use "fast inputs" to create content types inside the portal type, you have to define these content types as "hidden content types" in the Properties Tab of the portal type.

If the Use Case Analysis leads to the need of automatic generation methods for content documents using fast inputs, then manual creation of these content documents should not be proposed to the user. You should refer to Use cases to know if fast inputs are needed or not.

#

Action Names Should Be Explicitly For Users

The names are displayed to the user in the action menu on the document and is used for translation in other languages. Actions names should always be defined from an use case and end user point of view and not from a technical point of view.

#

Define And Translate Workflow Titles

The workflow title should be defined and translated.

It is needed to display workflow history on a document. The workflow titles are translated using Localizer (erp5_ui).

#

Define Count Method As countFolder On Module Listbox

"Count Method" should usually be defined as "countFolder" for listboxes used to view modules.

countFolder allows to show the number of document in a folder efficiently by using the ERP5 SQL Catalog. This result is also used to limit the results to retrieve using the list method. The method used to count documents in a module must use SQL for scalability.

#

Define Document Actions As Global Actions

Other actions are defined as global actions, they will automatically be present. If actions already exists on the portal type, you should remove them. Actions added for a document are:

  • Print: permission View, category object_print, id print and action string:${object_url}/Base_printPdf
  • History: permission View, category object_view, id history and action string:${object_url}/Base_viewHistory
  • Metadata: permission Manage properties, category object_view, id metadata and action string:${object_url}/Base_viewMetadata

The order of the actions of category object_view (which are defining tabs in the user interface) has to be the following : view, other views (example : details), history, metadata. For the ZMI view, the order goes from top to bottom. You should define the priority of actions according to that order (this is also valid for the modules portal types).

#

Define Module Author And Auditor In Roles Tab Based On Use Cases

Inside the Roles Tab, define the Author and Auditor roles according to the use cases.

In ERP5, all documents should follow the 5A Security model in which users are associated with roles in a per-module and/or per-document basis. An Author role should be assigned to all persons who have the right to create a new document inside a module. Those persons should also have an Auditor role because an Auditor is allowed to view documents, but not to create them. To avoid the repetitions in the roles, we can define many roles for the same "type" of person. For that, we just need to separate the roles by a ";" for example, in the field Role, we will have Author;Auditor. All the persons who have the possibility to access to a document to validate it or to modify it after it has been created should have an Auditor role on the module.

#

Define Module Default Actions On Portal Action Tool

Outside of the view action, all other default actions (Sort, Search, Print, Modify UI, Import, Export and Change State) of the Module Portal Type are defined as global actions on portal_actions tool, you don't have to include them as portal type actions ( like it was done before). Those actions are now replaced global actions, if they are already present on the portal type, you have to remove them:

  • Sort: permission View, category object_sort, id sort_on and action string:${object_url}/Folder_viewSortOnDialog
  • Search: permission View, category object_search, id search and action string:${object_url}/Folder_viewSearchDialog
  • Modify UI: permission View, category object_ui, id list_ui and action string:${object_url}/Base_viewUIDialog
  • Print: permission View, category object_print, id print and action string:${object_url}/Base_printPdf
  • Import Csv File: permission Modify portal content, category object_exchange, id csv_import and action string:${object_url}/Base_importCsvFileForm
  • Export Csv File: permission View, category object_exchange, id csv_export and action string:${object_url}/Base_exportCsvFileForm
  • Change Workflow State: permission Add portal content, category object_workflow, id change_workflow_state and action string:${object_url}/Base_changeWorkflowState
#

Define Report Actions As object_report Linked With View Permission

A specific fast report button is provided inside the action bar of ERP5 when needed. A well configured ERP5 site provides reports for almost all modules.

#

Define The Roles Allowed To Excecute A Transition

Define the roles allowed to execute the transitions.

This is required to be compatible with ERP5 5A security model. Refer to security and use cases specifications in order to know witch roles should be associated to a given transition.

#

Define Transition Titles From A Business Point Of View

Define the transition titles so that it makes sense from a business point of view.

The user must understand immediately the meaning of a workflow transition and localisation should be easy. For example, the "start_action" transition for a packing list has the sense of "ship". So the corresponding title should be "Ship". You should also define a name for the "Display in actions box". This name corresponds to what will be displayed to the user in the list of actions. The title field is used for the history display of the document.

#

Define Workflow Permission To Allow Redefinition On Workflow States

Define the permissions used by the workflow to 'View'( to view the object ), 'Modify portal content' ( to modify all information on the object) 'Access Content Information' ( to access/ to view all data saved on the object), 'Add Portal Content' (add actions on the document) and 'Delete objects' (delete sub-objects).

This allows you to redefine those permissions for each workflow states of the document. Refer to ERP5 Security Guidelines in order to learn more about security.

#

Define Workflow Titles From A Business Point Of View

Define the state titles so that it makes sense from a business point of view.

The user must understand immediately the meaning of a workflow state and localisation should be easy. For example, according to the standard movements management in ERP5, for packing lists there is a workflow state named "started" witch has the meaning of "shipped". The Id of this state should be "started" and its title should be "Shipped".

#

Do Not Test Required In Field View Form

This kind of constraint should be defined in Constraints documents and should to be checked in workflow transitions.

Checking a field as "required" can cause problems like not saving the data when the user clicks on the save button. The same applies to the use of External Validators scripts in fields.

You should not use it unless it cannot be checked using constraints or can put the system in an unstable state. For instance, web page titles, documents references are required fields because otherwise we couldn't find those documents. Password fields on the Person view have a confirmation with an external validator, because we don't want to lock out an user that mistakes his password.

Notice that it is accepted to define a field as required in dialogs. Thinking that a property will always be entered by the user is a mistake, you may think that a person will always have a name, but in real life for example you will find some cases like: "Mr Smith" without first name, "Betty" from Supplier company etc..

#

Forms Must Use Left, Right, Center, Bottom And Hidden Groups

An ERP5 form in view mode usually contains 5 groups named : left, right, center, bottom and hidden. Exception can be made for portal types with lots of properties, like Business Template.

These groups are needed to do a proper rendering of the form. Only the "bottom" and "hidden" groups are used in list mode. That means that "bottom" and "hidden" are the only groups required when you are designing a form to render the content of a module. For view mode, you need at least left, right and center; and bottom if your view contains a listbox. The groups are defined in the 'Order' tab of the form.

#

Set Security Roles On States And Transitions For Generic Business Templates

Generic business templates will have to contain security for 5A roles in workflows (states security and transitions).

In ERP5 Security model, security is splitted in two parts, one is to have 5 generic roles, and to use workflows to define security for thoses 5 generic roles (and in some cases also Owner or Anonymous roles), the second part of security definition is to define the mapping between specific business rules based on documents categories or user assignments ( usually group, site and function ) and those roles.

#

Hide Listbox Editable Fields On The Form

If a form contains a listbox with editable fields by listbox_property, those fields should be made hidden in the form by moving them in the "hidden" group.

Fields in hidden groups are not renderred at all (this is different from checking "hidden" property on field, in this case it's rendered as a <input type='hidden'/>). If the hidden group does not exist in the form, you should create it.

#

Include Module Base Categories In Business Template

Rationale: When creating a module in ERP5, the module's portal type will be attributed with certain base categories by default. These base categories need to be declared manually in the business template (using "Base Categories" from the "Portal Types" view) or need to be guessed by using the action Guess properties of Portal Types after adding the module's portal type to the business template.

Good Example:

bt5 "erp5_foo" declares in its "Base Categories" field in the "Portal Type" view:
  Foo Module | base_application
calling foo_module.setBaseApplication('CRM') in a configuration script works

Bad Example:

bt5 "erp5_foo" declares in its "Base Categories" field in the "Portal Type" view:
  Foo Module
calling foo_module.setBaseApplication('CRM') in a configuration script returns an AttributeError
#

Include Module Local Roles In Business Template

Include the module's local roles in the business template.

Rationale: When the business template is installed, roles defined on the module will not create local roles automatically, they must be explicitly included in the BT using "Local Roles" from "Detail" view.

#

Inside The Roles Tab, Assignor, Assignee, Associate And Auditor Must Be Defined

Inside the Roles Tab, define the Assignor, Assignee and Associate roles and sometimes Auditor according to the use cases,.

Rationale: In ERP5, all documents should follow the 5A Security model in which users are associated with roles in a per-module and/or per-document basis. Most of the times, the user who can create a document will have an "Assignor" role and the user who have to validate that document will have an "Assignee" role. Once all the roles are correctly defined on the portal type, you should do an "Update roles settings" so that all existing documents get the correct local roles.

#

Listbox Must Only Be Put In Form Bottom Group

Module form should only contain a listbox (and possibly editable fields) with id "listbox", in group "bottom". Default view for modules is always a listbox in list mode, its ID is by convention "listbox".

#

Listbox Selection Name Must Follow module_name_selection Pattern

By default, the name of the selection inside the listbox should be set follow "module_name_selection" naming (module_name will be the id of the module in lowercase).

The selection_name is used to find in a dictionary the parameters used inside a listbox. Generally we want a different selection_name for each listbox. In some cases, you could set the selection_name to another value.

#

ListField Or MultListField For Categories Must Use Item List Method

Always use the "item list method" from when you configure a ListField or MultiListField to handle categories in forms.

The way to render categories in pop-up menus must be consistent across various forms and must be configured from user preferences.

  • The categories titles are translated using Localizer (erp5_content).
  • The categories must be sorted by int_index, then by translated title, while respecting the hierarchical structure. The idea behind this is to have for example this ordering: A, B, P, Z, Others. With "Others" in last position, to achieve this, we have to set and int_index on "Others" category with a value greater than 0 (which is the default for A, B, P, Z).
  • The categories that cannot be viewed (ie. no View permission) by the user should not be displayed.
  • The method must be defined on the first level field library, and use the value preferred_category_child_item_list_method_id from preferences. The "items" TALES for the first field is horrible, but generic:
    getattr(here.portal_categories[field.getId().replace('my_', '', 1)],
      preferences.getPreference(
        'preferred_category_child_item_list_method_id',
        'getCategoryChildCompactLogicalPathItemList')
      )(
        local_sort_id=('int_index', 'translated_title'),
        checked_permission='View'
      )

    In some cases, the method used to render a list of categories could be different. For example, when handling values of the function category on a person, only leaves of the category tree should be displayed.
#

Place Simulation And Validation Fields At Bottom Of Right Group

Forms must be consistent.

#

Set At Least View Action On Module Action Tab

For both the Module Portal Type and Document Portal Type. Only the actions that are really needed on the module/document should be present. The minimal list of actions is:

  • View: permission View, category object_list and id view and action string:${object_url}/ModulePortalType_viewDocumentPortalTypeList
#

Set Content Permission On Fast Inputs

If fast inputs are used to modify existing documents, the fast input action should have the Modify portal content permission set. If it also creates new sub-documents, the Add portal content permission must also be set.

#

Set Description On Form Fields

The form field description is used to generate a tool tip. This description can be on the property sheet, or on the field. If the description of the property sheet definition is not good on the context (property sheet descriptions often are too technical), the description must be set on fields (on the first level of proxyfield).

#

Set Document Form Ids To PortalType_view

The id of the form should be as follows: PortalType_view.

This is defined in ERP5 naming convention.

#

Set Document Form Ids To PortalType_view

The form title should always represent what is displayed. Generally the title of the form is the portal type title.

#

Set Form Action Base_doSelect On Forms

#

Set Form Action To Base_edit

The form action is Base_edit.

#

Set Form Encytype to multipart/form-data When Using File Upload

The form enctype is multipart/form-data ( actually only important if you have file uploads )

#

Set Form Id To ModulePortalType_viewPortalTypeList

The id of the form should be as follows: ModulePortalType_viewPortalTypeList.

#

Set Form Title To What Is Displayed

The form title should always represent what is displayed.

#

Set List Method To contentValues On Document Form Listboxes

If the form contains a listbox, the corresponding "List Method" will be most of the time contentValues.

Generally we want to display sub documents. If you are not displaying sub objects but related objects, you will need to define another List Method, often category accessor, like getSourceProjectRelatedValueList.
In "default parameters" you have to specify "checked_permission | View" so that contentValues does not display sub-documents on which the user does not have the View permission.
searchFolder method uses SQL catalog to get documents so if the number of subdocuments is known to be small, it's usually faster to use contentValues directly; contentValues gets documents from Zope's object database.

#

Set Listbox Action To List Action On Document Form Listboxes

When clicking on the title of a listbox, we want the same listbox to be displayed in List mode so that selecting, deleting, filtering, etc. features become available. The form associated to the List action of a listbox should just contain a proxyfield of the initial listbox.

#

Set Listbox Selection Name To form_name_selection_name

If the form contains a listbox, the corresponding selection should be named as follows : form_name_selection_name (form_name is the id of the form in lowercase).

The selection_name is used to find in a dictionary the parameters used inside a listbox. Generally we want a different selection_name for each listbox. In some cases, you could set the selection_name to another value.

#

Set Listbox Title To Plural Of Portal Type Title If Applicable

If a listbox is configured so that only objects from one portal type can be displayed, then the title of the listbox should be set to the plural of the given portal type title (ex : Sale Orders should be the title of a listbox displaying "Sale Order" objects).

#

Set Post Method And Utf-8 Encoding On Document Forms

The form method is 'POST'. The encoding is UTF-8.

#

Set Priorities On Important Activities

Set priorities on non urgent activities so that important activities like indexing are executed first.

If your activities are not urgent, using a priority of 2 or 3 gives a higher probability that more important activities will be executed first.

#

Split Large Forms On Multiple Tabs

When there is too much information to fit on one single form, multiple views can be shown. If using multiple tabs, the first tab should contain the most useful information. Information from the same concept should be on the same tab. When working with an order for example, you should have a tab for general information, payment information or discount information.

#

Use Correct Names For Simulation And Validation Titles

All the fields representing simulation_state and validation_state should be my_translated_simulation_state_title and my_translated_validation_state_title.

The workflow states should be automatically translated when the user changes the current language. The workflow states titles are translated using Localizer.

#

Use form_list Page Template On Forms

#

Use getTranslatedId To Display Document Id In Listbox Or Form

Use getTranslatedId when you want to display the special ids of a document in a listbox or in a form (ex : default_address sub object).

Objects with reserved ids like "default_address" have a special meaning and behaviour in ERP5. It is necessary to display this information to the user and to be able to do some localisation.

#

Use Method Post And UTF-8 Encoding On Forms

The form method is 'POST'. The encoding is UTF-8

#

Use Proxy Fields Of Proxy Fields In Forms

Use proxyfields of proxyfields to create forms. Each Business Template provides libraries of fields that have to be used to define the forms associated to modules and documents.

All the forms of an ERP5 site have to be consistent. The maintenance of the forms has to be easy.

  • The fields used to define forms are proxyfields of proxyfields. Actually ERP5 Base provides a field library in which the default rendering of each kind of field is defined.
  • The field libraries contained in other business templates are defining the logic associated to the field.
    • Example : Shipping Date
    • In the Base field library, a "Date" field is defining that dates are displayed using the date format chosen by the user in its preference document.
    • In the Trade BT, an order field library defines that "Shipping Date" is a proxyfield of the "Date " field and that it will handle the start_date property.
    • In the order or packing_list view form, a proxyfield of "Shipping Date" is used to display the shipping date.
#

Use Translated Portal Type To Display Portal Type

Use always translated_portal_type if you want to display the portal type of a document in a form, because this allows to provide automatic translation of the portal_type property. The portal types titles are translated using Localizer (erp5_ui).

#

Workflow Validation Scripts Must Be Well Defined

All the scripts that should validate the workflow transitions should be well defined.

It is very important to do checks during the validation step to ensure that all data is consistent and that everything is well defined. Checking the consistency of the data in ERP5 is done on user action workflow transitions and not when entering data.

"Permanent" checks have to be implemented in constraints. Permanent checks are checks that should apply at any time, for example that an order has a source and a destination. The workflow script only have to call sci['object'].Base_checkConsistency() to perform constraint based checks.
"Temporary" checks have to be implemented in the workflow script. Temporary checks are checks that should only apply when we try to do the action, for example that client information is valid at the time we send an invoice.

#

Workflow Validation Scripts Must Return Translated Messages

Validation scripts must return translated messages..

Messages from validation scripts will be present in the application's status message and in the workflow history. Use Products.ERP5Type.Message class so that translation is done only when the message is displayed to the user (this allow translation of workflow history).

Crime

#

Never Allow Relation String Fields To Set Relations To Categories

Relation string fields should never permit to define relations with categories objects (portal type Category).

The notion of category is not easy to understand for an end user and having to select a correct category value among a huge list is bad interface. Category should not be present in the Portal Type field of a relation string field (example : my_source_title, my_destination_title, my_resource_title field).

#

Never Set Search Row And Select Column On Listbox Inside Document View

Never check the "Search Row" and "Select Column" properties for a listbox included in a document view form. These properties are reserved for listboxes used to view a module object view.

Searching and selecting documents in a listbox is not allowed in view mode. It is allowed to display several listboxes but without "search row" et "select column" inside a single view form.

#

Never Show Or Make User Work With Document Id

The ERP5 Document Id is a technical property in ERP5 and should not be significant for users. Ids should never (and no longer) be used in ERP5 Forms. For an ERP5 user, an ERP5 document has to be identified by either its title, reference or int_index but not by its id which is a technical property.

#

Never Use Multiple Modules For Person Or Organisation

The Person and Organisation modules are intended to store objects which represent people and organisations of many different kinds: customers, suppliers, staff, etc. It is a mistake to create multiple modules and types to represent the different kinds of people and organisations for two reasons: it breaks the unification principle in ERP5 and it requires to update so many relation fields everywhere. Instead, use the role category to achieve the same result. Make also sure that workflows on Person and Organisation as well as security are designed based on the role category value(s). With this approach, a Person who used to be a staff and then becomes a customer can be tracked from the same object. Do not hesitate to implement 'big' workflows which consist in the union of all possible cases. It may sound complex or heavy, but it is the only way to achieve the unification of people and organisations. In the consulting phase, the workflow analysis does not need obviously to focus on the unified complex workflow but rather on simple workflows on per use case base (ex. customer validation, supplier validation, etc.). It is the responsibility of the implementer to find a way to unify all these workflows in a single workflow. The only exceptions to this rule which we know are some cases in which one wants to use a kind of buffer module to import people and organisations before copying them into the real module, or some cases in which one wants to create a new kind of node (ex. animal).