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).