ERP5 Handbook/Getting Started

TODO: Proof reading and extending by experts is needed. = Getting Started =

Terminology
ERP stands for Enterprise Resource Planning

(FIXME: What does a "ERP system" do? Can you summarize it in one sentence?)

(FIXME: What kind of person would ever use an ERP?)

(FIXME: Rewrite the cryptic english...)

Basic Ideas
ERP systems are quite complicated - they have to implement as much as possible the business logic of a company. ERP5 distinguish itself from other ERP systems (open and closed source) with its coherency from the lowest - theoretical - level. It is based on a well developed theoretical model and to understand the key concepts of ERP5 it is needed to understand briefly that model. Of course basic understanding of technical aspects is needed too.

Five classes - introduction
ERP5 defines an abstract model of business management. Thanks to a clean abstraction layer, new or specialised business modules can be implemented in a consistent way. This abstract business model can both be used to represent internal management activities as well as commercial and management activities across a group of companies

The ERP5 abstract model is based on 5 classes:


 * Resource: a resource describes an abstract resource in a business process (e.g. a skill of an individual, a currency, a raw material, a product). Relations between nodes allow to define BOM (Base Object Model) as well as prototypes.
 * Node: a node is a place which can receive amounts of resources and send amounts of resources. Nodes can relate to physical entities (e.g. a workshop which receives raw material, processes it and sends it) or abstract entities (e.g. a bank account which can receive money). Stocks are a kind of Node. Metanodes are nodes which contain other nodes. A company is a metanode. A project is both a resource and a node.
 * Movements: a movement describes the movement of an amount of resource between two nodes at a given time and for a given duration. For example, a movement may send raw material from a stock to a workshop, another movement may send money from one account to another.
 * Path: a path allows to define a way for a node to access a resource it may eventually need. Prices and commercial profiles may be attached to a path in order to define the default price for a given resource procured at a given maker. Path may also define the way a workshop gets its resource from a stock. Path have a start date and an end date. Path may be used to represent the assignment of an individual to a temporary project.
 * Item: an item describes a physical instance of a resource. A movement can be expanded into a series of trackable movements through items. items also allow to define how a given amount of resources was actually shipped (e.g. parcels, serial numbers of items in each container, etc.)

Those five classes are sufficient to represent business ranging from chemical plants to manufacturing, trading or services, and can model everything that goes on in an organisation. For example:


 * a sale of goods is a movement of a certain quantity of a product (resource) from our company (node) to the buyer (node) at a given price (path)
 * an accounting entry is a movement of some money (resource) between two accounts (nodes)
 * an phone call is a movement of an employee's time (resource) between the two interlocutors
 * a training is a movement of skill (resource) from nowhere (surprise!) to the trainee

It sounds very abstract, but that's exactly why it is so powerful...

Modelling reality like this, we use the same attributes to describe very different things: every movement has its source and destination, plus some variations of them (e.g. in sale transaction source is a physical location from which goods are shipped, while source_section is the owner who is selling the goods). And we can use standard, optimised API to calculate the results.

The key question is always: how much do we have of (this or that). In this model, a node doesn't really have "content"; when we want to know how much goods are there in a warehouse, or what is the amount on account, or how much time our support guy spent answering phone calls, we sum up quantities of all movements incoming to and outgoing from the node. For this, we use a standard "getInventory" method which serve every purpose of this kind.

Simulation model
Simulations are one of the most powerful features of ERP5, although they are entirely hidden from the user. The idea is that movements which are supposed to have an impact on the future - or, in other words, which are going to cause some other movements - are equipped with so-called "rules" which are used to generate "simulation movements", which in turn can have their own rules and generate further simulation movements, thus "simulating" the future of our business. When the future becomes present and it's time to create real movements, we use simulation movements to check what, how much, for whom etc.

It is best explained on an example: if we accept a sale order, we know we'll sooner or later have to ship; and once we ship, we'd like to invoice; and once we invoice, we are going to get money. So a sale order is broken into lines, each line representing delivery of one product, and each line generates a simulation movement representing shipment. Shipment then generates simulated invoice line, etc.

The benefit of this is twofold:
 * once we accepted an order, we can get a financial forecast straight from the system
 * when we start packing, we can aggregate orders in any way we like - we don't have to pack order by order, instead we can generate a separate packing list for each product line, or combine all orders from the same customer into one big list, or even do both - create a separate packing list for products from the same product line ordered by the same customer over the last month, for instance. The point is to equip our ERP5 with appropriately configured "builders" which will do the job.

Affiliation between MySQL and ZODB
In ERP5 all objects are put into ZODB (Zope Object Database) and they are indexed in SQL database (run on MySQL RDBMS). Such attitude results in fast object searching and access, and from other side - easy object manipulation.

Reporting and printing
Reports allow users to generate summaries and specifications for the data stored in modules. Reports can be generated in two forms: an OpenOffice.org document or a PDF form.



Reports are attached to the specific module. If there are any reports defined for that module, then on the standard module view form, with a listbox containing that module's data, the report icon will appear in the toolbar. (if there's no data the icon will still appear :) )

Although reports are in this way associated with the module and one expects to find data related to the module, they may practically contain any kind of data.

The detailed HowTos on creating reports may be found on ERP5 Wiki pages, both for OpenOffice reports and PDF reports. There is also a guide on how to add created reports to ERP5 site.

Background process invocation - CMFActivity system
ERP system logic might be very complicated - any scripts can be attached to any object in the system. It is possible that on encumbered systems the server resources become overloaded. The advantage of this approach is that the consultant or application manager might want to have the ability to set up some scripts one by one, or to choose some special conditions which will happen before invoking some actions.

ERP5 provides a built-in background process invocation system called CMFActivity. With this the resource-consuming tasks can be prioritised and put into background. They will be invoked in whatever desired order, one at a time, such that resources of the machine won't be overconsumed. After invoking such tasks an icon appears on the user interfaces of objects which are directly related to this object, informing the user that this object is waiting to be processed by a pending activity.

On a properly configured system CMFActivity may send messages about failed tasks. Developers and consultants are able to attach a special console - from Zope, and even from a system shell - to observe, cancel or force invocation of activities.

In technical sense every task put into activity is a row in the SQL table. Here is described with each object what activity shall be run, what that activity is and other properties. CMFActivity supports clustering and load-balancing of task queues.

In depth background process invocation is described on the ERP5 wiki page HowToUseTheCmfActivityTool.

Categories
The ERP5 system is based on categories, they are used to define the categorization and descriptive relation between objects in the system.

Categories are accessible and configurable through the Zope interface. To do this, go to:

[your_site]/portal_categories

(user "zope" can access if from the "My favourites" dropdown menu in the top left corner)

You will see a long list of "Base Categories". Click on any of them, you'll see it has lots of fields which you don't need to know anything about at this stage. Under the Action dropdown menu there is an option with which you can create a sub-category. Then you can create sub-sub-categories, and for each of those sub-sub-sub-categories, and so on ad infinitum.

Some base categories (region, site, group, function, skill...) are used for categorization, so you can build your trees within them; others (source, destination, subordination...) are used for setting relations between objects, and they don't need any subcategories.

The system accesses categories using special accessors, which makes categories translatable.

Categorization usage
By defining a tree in a given base category a consultant is able to set up categorization with required depth. Examples of categorization categories are:
 * region - to tell where a Person lives or where the Organisation has its headquarters
 * skill - to tell who can do what
 * quantity_unit - for definitions of quantity units for resources
 * delivery_mode - describes modes of transport for orders
 * gap - used for General Accounting Plan

The beauty of this category mechanism in ERP5 is that you can assign an object to one or more categories at your discretion, and that the notion of "category membership" goes all the way up the base category tree (meaning that if an object belongs to category "a/b/c", it belongs to category "a/b" and "a" too. That way, you can set up a category tree:

skill/dance skill/dance/latino skill/dance/latino/samba skill/dance/latino/salsa skill/dance/latino/rumba skill/dance/classic skill/dance/classic/waltz skill/dance/classic/tango skill/dance/ballet skill/coding/c

Then assign persons to categories:


 * Joan:skill/dance/latino/samba
 * skill/dance/classic/tango


 * Mary:skill/dance/latino


 * Paul:skill/dance/ballet


 * Peter:skill/coding/c

Now, if you ask the system who can dance samba - you get Joan, Latino - you get Mary and Joan, classic/tango - Joan, classic - Joan, too; ask who can dance anything - you get Mary, Joan and Paul; and if you want to know who can't dance at all, you can get it too. All by using auto-generated accessor methods, without any fuss.

To see it in action, go to the "Persons" module and turn on the "domain tree" mode of the module's listbox; select "skill" from the dropdown, and you can browse your dancing resources.

If you plan to open a dance school, then the system is perfect for you.

Have a look at the Understanding listboxes section for more details, and some screenshots.

Relation usage
As opposed to categorization usage some categories are used for relation system. Lets say, that we have Organisation object ACME and Sale Order object SO-1. We can define a relation between SO-1 and ACME using a source category. The sale system is implemented in such a way that the source category means that goods will be send from ACME.

Most popular relation categories are:
 * source
 * source_section
 * destination
 * destination_section
 * parent

Using relations is described in detail here: http://wiki.erp5.org/HowToConfigureRelationField

TODO: How reader shall identify distinction between categories in portal_categories?

General introduction


Workflows are one of the key concepts of ERP5. They are used everywhere, for everything. They are so important because a workflow represents a process - and everything that is done in a business is a process. A workflow can represent any process, e.g. editing and publishing an article, recruiting a person, receiving and processing a sale order, making an accounting entry etc.


 * States and Transitions

When an object is managed by a workflow, it means that it is subject to a procedure which this workflow represents. A procedure consists of some states and transitions between the states, and can be nicely represented by a graph, where boxes represent states, and arrows represent transitions. The workflow has an initial state, which the object assumes when it is created. If a transition is made, it changes its state to a destination state of the transition. Then another transition can be made, and so on until the object reaches a state from which there is no more transitions.





ERP5 standard interface shows the object's workflow state in the main form, and available transitions in the "Action" dropdown.


 * Security

An important thing a workflow does is managing access rights to an object. For example, an article which is in a "draft" state should be accessible only to its author (for read and write), while "published" article should be readable by everyone and writable by nobody. Access rights can be defined and set separately for every workflow state.


 * Conditions

A transition can be made available only to users who have certain rights in the system - for example, you have to be a "chief editor" to be allowed to publish an article. If you are not, you won't see the "Publish" action in your action box. A transition can also depend or other object properties - an article can be submitted for publication only if it contains some text, or an accounting entry can be confirmed only if credit and debit are equal.


 * Side effects

Workflow transitions can have "side effects" - actions to be executed when a transition is being made. Sticking to our publication workflow, when a document is being published, the system can send email notification to all subscribers. A more business-oriented example is that when a sale order is confirmed, the system generates a planned invoice.


 * Interaction workflows

This is a different kind of a workflow - it has no states, and no transitions. Instead, it has "interactions", which are triggered when a given action is being made on an object. Interaction workflows are basically a cleaner and more portable way of implementing side effects - if we want a notification send when a document is published, we can do it by tweaking publication workflow, but we can instead add an interaction workflow with a "send notifications" interaction hooked to the "publish" action of the publication workflow.


 * Edit workflow

This is a special workflow, which is hooked to almost every object in ERP5. It is quite unusual because it has only one state - "current" - and one transition which goes back to the same state. This transition is executed every time an object is edited; the sole purpose of this workflow is recording the object's history.

How to implement
See http://wiki.erp5.org/HowToUseAndDefineWorkflows for detailed instruction and technical information.

Introduction to security
Please refer to this article:

http://wiki.erp5.org/HowToDesignSecurity

for guidelines about how to design security for an ERP5 application, and to this:

http://wiki.erp5.org/HowTo/HowToUseNewSecurity

for how to implement it.