ERP5 Handbook/Lets go...

Let's go...

Installation of the core

An alternative way of installing and running an ERP5 site is by using RPM repositories. Below is a short and concise description of how to make ERP5 up and running in just a few steps.

First of all we need to get the Zope/ERP5 sources as well as some additional software packages. If there's a Zope installation in the system, we have to uninstall it. ERP5 uses a patched Zope version which is downloaded and installed together with ERP5. It is possible to have two installations of Zope, but that is an advanced topic and won't be covered here.

For very good downloading instructions read the Download How To on ERP5 home site. After successfully downloading and installing all the packages we can proceed with configuration and setup.

Still as a root user we go to the Products sub-directory of a newly created Zope INSTANCE_HOME directory and run the svn_update script which will do all the hard work. Since INSTANCE_HOME should be in /var/lib/zope/ we type:

cd /var/lib/zope/Products
ls (as shown on a screenshot this should show us some dirs and a script)
sh svn_update.sh

After the data from SVN repository has been updated we need to make sure Zope can access it. We do it by making all the sub-directories and files therein Zope's own:

chown -R zope:zope *

On the console it should look like this:

One last thing is needed to be done, before we run the Zope instance. We need to create the main manager user. It doesn't matter what the username will be, as long as it contains only the standard letters. For example if we'd want to create user 'zope' with password 'zope' we need to run the commands:

zopectl stop (to make sure Zope is stopped for adding a user)
zopectl adduser zope zope
zopectl start

With the output not unlike this:

Don't be scared by DeprecationWarnings. If you don't mind them, they won't mind you. :)
After the final command Zope should be up and running which we can check, by going to the address: http://localhost:9080/manage in an internet browser of our choosing.
The Authorization Dialog should pop-up asking for username and password. We enter the newly created zope user name and password.

If the dialog does not appear and the browser displays some kind of 'Unable to connect' message it means the Zope instance didn't truly startup. To check what's preventing the correct start up, it's best to go to zopectl interface and check the startup output. To do that we can enter:

zopectl

and after receiving the zopectl> prompt either enter:

zopectl> logtail

to display last lines of the startup log (hopefully with error message there) or type :

zopectl> stop
zopectl> foreground
(or zopectl> fg)

to see whole output of the startup procedure. Eliminating eventual errors is out of scope of this section.

Before we go on to creating and starting the ERP5 site, we need to make sure it has its very own space in the MySQL server. This is important since the default test database that exists in MySQL is used for the testing procedures and using it also for the regular ERP5 site might cause unexpected problems. To make a erp5 database for our new site we need to do the following (we assume the name of the database is 'erp5', but that can be anything else):

mysql (enter the mysql interface)
mysql> CREATE DATABASE erp5;
mysql> GRANT ALL ON erp5.* TO erp5@localhost IDENTIFIED BY 'erp5';
mysql> quit

The output should look similar to this:

This will create an 'erp5' database which can be accessed by MySQL user 'erp5@localhost' with password 'erp5' just like that:

Once we have database set up, Zope up and running and we're logged in as a manager user, we can install ERP5 site object to be able to use all the wonders of ERP5.

While in the root manage page like the one on the screenshot above we should choose from the dropdown box an 'ERP5 Site' object. After that we are presented with the configuration page for the new ERP5 site. The only thing that should be reconfigured is the ERP5/MySQL connectivity settings. Here in all three fields we enter the name of the database, user of that database and his password.
In our case that would be: erp5 erp5 erp5
The database type should stay as an InnoDB.

Finally we click the 'Create a new ERP5 instance' button and wait a bit for everything to set itself up.

If the process is successful we will be redirected to the front page of ERP5 site, just like the one on the screenshot below.

Congratulations!

Enabling preferences

Before going further, enable default_site_preference by navigating to http://localhost:9080/erp5/default_site_preference and choosing Action...->Enable Preference from actionbox. Without enabling preference you might have cryptic messages (related to user interface - forms).

Validating portal rules

New simulation system in ERP5 need rules to be validated. Navigate to http://localhost:9080/erp5/portal_rules and validate every rule in that container, using rule's action box or mass validation action from container. Without validated rules many simulations won't be created, and builders won't be able to generate documents.

Adding packages

As you probably noticed, the screen is almost empty and there is nothing you can do, except to stare in admiration at the beautiful logo of ERP5. This is normal - it is because you created an empty site and haven't yet installed any packages - we call them "business templates" (see Business Templates for more).

Have a look at "Manage Business Templates" tool (accessible from "My favourites" dropdown in the top left corner) - you will see that you have only three templates: core, xhtml_style and mysql_innodb_catalog. These three are needed to make ERP5 running and are installed upon bootstrap.

To get started, install erp5_base first - it brings the most basic functionality, and anyway is required by all the other templates.

See Installation techniques for instructions how to download, install and upgrade your templates.

General Idea

Typical Business Template repository configuration

From developer point of view Business Template is a package which includes developer works with some metadata and functionality typical for packaging system: dependencies, provisions, scripts, installation/upgrade/uninstallation system. Developer is able to put almost any modification of ZODB into Business Template. There are some restrictions, but BT system is evolving all the time.

From consultant point of view Business Template is installable/upgradeable/uninstallable set of objects for which dependency will be computed automatically. Business Template file - ending with .bt5 extensions usually - could be compared to popular .rpm or .deb file format. Business Template system in ERP5 is like yum, rpmdrake or dselect.

Business Template files exists in some kind of repository - on http server, on local filesystem - with generated XML file bt5list. One ERP5 installation is able to be connected to many Business Template repositories; and of course developers are able to publish many types of repositories, e.g. development, testing or stable.

erp5_base

This bt5 installs three basic data types: Person, Organisation and Currency, and some auxiliary types. It also installs three modules:

• person_module (Persons)
• organisation_module (Organisations)
• currency_module (Currencies)

It also installs some mechanism for processing basic information about people and organisations they might be working for.

Basic use case

We would like to record information about a company and one person who is working for this company.

Step 1 - create an Organisation

Go to the Organisations module, and select "Add Organisation" from the "Action" dropdown. A new form will appear. Fill it in with some data.

Note the "Contact" listbox at the bottom of the first tab ("View"). It is empty; if you enter an email and save the form, after a while the listbox will show "default_email" - it is an object of a type "Email", which contains the email address you've just entered. The way it works is that the "email" field on the Organisation's "View" tab is somehow linked to the "default_email" object. You can add more email addresses; if you'd like to change the default email, change the id of "default_email" to anything you like, and then change the id of the other email into "default_email". It works the same way for phone number, fax and address, and many other things.

If you want to record country or activity you have to go to portal_categories and create subcategory trees under the appropriate base categories (region and activity in this case)).

Step 2 - create a Person

Go to the person module, select "Add Person" from the "Action" dropdown. Fill in the person's name, email and other information.

Step 3 - employ the Person

Go to the person's "View" tab - there is a field labelled "Organisation", with a little gear next to it. This is called "Relation String Field". Click on the gear - you'll see a list of organisations you've created before. Tick one and click "Update Relation" button. Done - the person now works for this company. Now, next to the gear, you can see a little airplane - it takes you straight to the organisation the person is working for.

Look at the "Career" tab - there is a listbox "Career Steps", with one object labelled "default_career". This is an object of the type "Career", and it represents an employment contract; it is treated as current employment, because it's id is "default_career". You can edit the object; however, despite being the default, it is not active because it's status is "Draft" - this is a workflow state. To start the employment, select "Start Career Step" from the "Action" dropdown - the status will change, and the object will become read-only.

There is a shortcut for terminating the current employment and starting up a new one - go to the Person object and from the Action dropdown select "Terminate the current career step" - and see what happens.

Step 4 - make the person a user

To let the newly created person log into the system, you have to first create an Assignment for him (Action->Add Assignment), then open it (Action->Open). You don't even have to fill any data into the assignment, it just has to be there.

Then, go back to the person, select "Assignment" tab, give him a login and password, and you're done.

Caveat: if you use a bit older version of ERP5, you can skip the assignment part, but the Career tab has to say that the person's role is "internal", and login and password are on "Details" tab.

erp5_trade

This bt5 installs data types:

• Internal Packing List
• Internal Packing List Line
• Purchase Order
• Purchase Order
• Purchase Packing List
• Purchase Packing List Line
• Sale Order
• Sale Order Line
• Sale Packing List
• Sale Packing List Line
• and many others

Most important modules provided by this business template are:

• internal_packing_list_module (Internal Packing Lists)
• sale_order_module (Sale Orders)
• purchase_order_module (Purchase Orders)
• sale_packing_list_module (Sale Packing Lists)
• purchase_packing_list_module (Purchase Packing Lists)

Basic use case

Assumption: erp5_base, erp5_pdm and erp5_trade Business Templates properly installed.

Scenario description

We are ACME corp., John Smith is our sale and purchase manager. We want to purchase some goods from our supplier and then sell them to our customers.

System preparation

Create organisation ACME corp. in Organisations module, create John Smith in Persons. Also create EUR currency in Currencies.

Purchasing goods...

Go into Purchase Orders, create new Purchase Order.

...and selling them

• instruct how to add erp5_base, erp5_trade and erp5_pdm from Nexedi's BT repository
• basic use of installed BTses: add product, add companies, persons, add sale order, watch product movement history
• invoke desire in reader to play with ERP5
• clean up above - it is copy/pasted - need rearrangement