Welcome to koalixcrm’s documentation!¶
Contents:
koalixcrm Installation¶
on Windows 10 Version 1703¶
Install Python 3.6.2¶
Download from https://www.python.org/downloads/ Install python with the defaults
Install FOP 2.2¶
Download and install java from oracle website Download fop2.2 from apache fop website and install
Install koalixcrm app¶
Run command C:UsersYourUserAppDataLocalProgramsPythonPython36-32Scriptspip.exe install koalix-crm
Setup django project¶
Run command C:UsersYourUserAppDataLocalProgramsPythonPython36-32Scriptsdjango-admin.exe startproject test_koalixcrm mkdir test_koalixcrmmedia mkdir test_koalixcrmmediauploads
on ubuntu 17.04¶
Install required programs on your ubuntu¶
sudo bash apt-get install fop virtualenv python3.5 exit
Create a virtual python environment for the koalixcrm project¶
mkdir ~/test_koalixcrm_env virtualenv –no-site-package –python=/usr/bin/python3.5 ~/test_koalixcrm_env source /test_koalixcrm_env/bin/activate pip install koalix-crm
Create a generic django project¶
cd ~ django-admin startproject test_koalixcrm
Common on all Operating Systems¶
Import koalixcrm to your project¶
Open the file called settings.py
Search in the file the variable definition “INSTALLED_APPS” Add following lines to the at the end of INSTALLED_APPS: ‘koalixcrm.crm’, ‘koalixcrm.accounting’, ‘koalixcrm.djangoUserExtension’, ‘koalixcrm.subscriptions’, ‘filebrowser’
Create a new variable defintion “KOALIXCRM_PLUGIN” KOALIXCRM_PLUGINS = (
‘koalixcrm.subscriptions’,)
At the very end of the seetings.py file add the following lines: STATIC_URL = ‘/static/’ STATIC_ROOT = os.path.join(BASE_DIR, ‘static/’)
MEDIA_URL = “/media/” MEDIA_ROOT = os.path.join(BASE_DIR, ‘’)
PROJECT_ROOT = BASE_DIR
# Settings specific for koalixcrm PDF_OUTPUT_ROOT = os.path.join(STATIC_ROOT, ‘pdf/’) FOP_
# Settings specific for filebrowser FILEBROWSER_DIRECTORY = ‘uploads/’
Enable the customized additional view for filebrowser¶
Open the file called urls.py Completely rewrite the file with following content
from django.conf.urls.static import * from django.contrib.staticfiles.urls import static from django.contrib import admin from filebrowser.sites import FileBrowserSite from django.core.files.storage import DefaultStorage
site = FileBrowserSite(name=”filebrowser”, storage=DefaultStorage()) customsite = FileBrowserSite(name=’custom_filebrowser’, storage=DefaultStorage()) customsite.directory = “uploads/”
admin.autodiscover()
- urlpatterns = [
- url(r’^admin/filebrowser/’, customsite.urls), url(r’^admin/’, admin.site.urls),
] urlpatterns += static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)
Afterwards start the django application¶
cd ~/test_koalixcrm python manage.py makemigrations python manage.py migrate python manage.py createsuperuser python manage.py runserver 127.0.0.1:8000
Log in to the admin website¶
What you want to do next is of cause the test the software. Visit your http://127.0.0.1:8000/admin, log in and start testing.
Intro¶
This Intro should give you an overview of koalixcrm’s basic functions and structure.
Basic Structure¶
koalixcrm tries to keep its structure near the real world objects it represents. Lets say you want to register a customer in koalixcrm then you find a customer in your koalixcrm. When you receive a question for a quote, you find the quote in your koalixcrm. Same for many kind of business objects you know in your company. Every such real world objects is represented in the admin start page (called “dashboard”) as row of the Applications table. Every object has a name - of cause - an Add and a Change button. When you want to create a customer you just press the “Add” button in the Customers row and you will see a form (called “object_modify_view”) to fill out for your customer. By pressing the Change or name button (eg “Customers”) of the object you see a list of all objects (called “objects_list”) you have already saved.
dashboard¶
The dashboard (“Site Administration”) is the place you start after logging in. In the dashboard you find a list of all object types (called objectlist) in three groups (called applications): crm, accounting and djangoUserExtentions.
Administrator only¶
When you are administrator, you can also see a group called auth where you can manage users and groups. During the installation you are asked to create a first, administrator user. Every new user after that starts with no privileges. To be able to log in to koalixcrm the new user must be moderator. When you want to create an accounting-only user you must select all accounting privileges in the user_modification_view.
objects_list¶
From the dashboard you are able to select one object type by clicking on the name of it. What you get is a quite detailed list of objects of this object type.
To modify an object you simply press press on the id of the object to get to a form-view of the object.
Adding A New Object To The List¶
To add a new object to the list you simply have to press the “Add button” on the top right of the page
Apply An Action On An Object¶
Applying actions to objects is a basic point of using koalixcrm. To be able to remove objects from your list you have to select all objects you want to remove by clicking on the checkbox on the left side of the object list.
When you finish making your selection you will see a new selection field rising from the bottom of your page. Here you can select what action you would like to to apply to the objects. Serveral things can be done with these actions.
Apply A Filter On The List Of Objects¶
On some list of objects you may apply filter functions. This filter function can be found on the right side of the page. Depending on the filter you apply on the list you get a smaller number of objects
Do A Search Through All Objects¶
The more objects you registered in your system, the more difficult it becomes to find the one you are looking for. On some object lists you will find a search box. The keywords you enter in this searchbox will be searched in the objects name, id, description and so on. All objects that include your selected keywords will be displayed in the list.
object_modify_view¶
Lets say you logged into the system as a moderator with enough privileges to modify a customer. You first access the customer objects list. You will find your exiting list of customers on the screen
As soon as you press on the button “ADD CUSTOMER”, the browser will load a new screen: The “object modify view”. In the modify view you will find several fields to fill out. As soon as the fields have been filled out you can press the “SAVE” button at the bottom of the page. The field entries are then transmit and validated by the application.
The fields which have a bold title are “must”-fields - they have to be filled out before saving the customer.
In case you have entered something wrong or invalid, the application will complain and ask you to correct the invalid data.
Some of the optional fields are hidden (collapsed) by default. By pressing the “SHOW” button beside “POSTAL ADDRESS FOR CONTACT” you can expand these fields.
Tutorial¶
This tutorial is going to teach you how to
- Create a customer
- Create a currency
- Create a product
- Create a contract
- Create a quote
- Create an invoice
- Set up your accounting
- Record an invoice in your accounting
- Record a customer payment in the accounting
Before you start I recommend you first have a look into the Intro. This gives you an idea of the basic structure of koalixcrm. When you understand the structure and functions of koalixcrm or any other large Django application you are ready to start with the tutorial. Further, have a look at the koalixcrm Installation section
Create Your First Customer¶
Let say you want to Register the following Customer: Private address:
John Smith
Ave 1
90990 Smallville
Phone:
Mobile:
Email:
Business address:
Smith and Sons
Ave 2
120987 Largeville
Phone:
Mobile:
Email:
Logging In Adminpage¶
Depending on where you installed your koalixcrm - in this tutorial I assume you installed it on your localhost (the computer you are sitting in front of) - visit http://localhost/admin in your browser.
fill out the username and password you set during koalixcrm Installation in the syncdb procedure.
Create a Currency¶
Select “Add Customer”¶
After login you will see the dashboard you already know from the Intro. In the Applications list select the “Customer” - add button
Fill out Fields¶
After adding the customer you will have to fill out all required values to get a valid registered customer. You will have to fill out “postal address” and “phone address”. Further you will need to add a new “Default Billing Cycle” This can be added by pressing the greeen “plus” sign beside the “Default billing cycle” drop down box.
A new page will open up and give you the ability to add a new billing cycle. Fill in the values as described in the image below:
After you filled in all required values you will have to click on the save button. This click will bring you back to the customer adding view … and you will see that the default payment method is now set. Next is the customer group, we have to do exactly the same. Click on the green “plus” sign beside the groups list and you will soon get a pop up where you can add your first default customer group. Fill in the values as described in the image below
After that you have to fill out all the addresses defined in the header of this tutorial. Finish the customer registration by pressing the save button
Look at your first Customer¶
Ok now we have registered your first Customer. Of course to have a customer is not that interesting, we hope that a customer is going to order something, or needs an invoice, a quote or something else. This will be the next step of the tutorial. But first have a look at your bright shiny customer by selecting customer’s id the dashboard as described in the Intro.
Create Your First Contract¶
I expect you are still looking at your first customer we just created. The next step is to click the checkbox to the left of your customer on the CRM customer list and look at the the actions list that appears on the bottom of the page.
Select “Create Contract” from this list. This will bring you to the “add contract” form. The advantage of doing it this way - instead of adding a new contract through the dashboard - is that you have some values, like the default customer, already set. this will give you some additional seconds for your daily work. I expect you are a little bit surprised … where do I select that I want to have a quote or an invoice? Well, in koalixcrm a contract is not an invoice and a contract is not a quote. A contract is simply a place to store all kind of documents that are related to the contract. This can of course be a invoice or a quote but also purchase orders and so on.
Fill in the description field, then by clicking on the save button you have finished the creation of a contract.
Create Your First Quote¶
Until now there are no products, no prices and no units registered. In order to be able to offer a product to a customer we need some products first…. you could do it the lazy way by adding the product while registering the quote but in this case we are going to register the products, units and prices before we create the quote.
Create Your First Product¶
To create your first product visit the dashboard by either following the breadcrumps back to the dashboard
or visit http://localhost/admin again. Press the Add button next to Units to access the Unit adding form. Now fill out all the required fields to register the unit “hours”
Press save, add an other unit by again pressing the add button. Now we create a unit “minute”.
Press save and go back to the dashboard
As we have registered some units, now we are able to create a product.
Press the Products add button to get to the products adding form. We start with a common product called Manpower. Fill all fields with the following values:
as you know every product has its price specially manpower - time is money. That’s why we have to add at least one price for this product by giving the Prices fields the following values.
You will see an other part of this form called Unit Transfroms. Unit Transforms are sometimes needed when, for example, you have stacks of certain products but only one price per piece. Leave this blank when you only have one unit for one product.
After adding this product you are ready to create your first Quote by going to your dashboard. Open Contracts, select the check box beside the contract you want to change and select “Create Quote” from the Actions list. A form will open for you to fill out your fist quote.
As you can see, there are lots of predefined values because we created the quote with the action instead of via dashboard and Quote Add. There are three major parts of a quote:
- First the general values like “valid until”, “description” and so on
- Second are role positions of the quote
- Lastly are Addresses related to the Contract
By pressing the “+” sign you can add as many positions as you like. Fill in the values as described below.
Click on the save button to finish your first quote. Go back to the dashboard, go to quotes and select the newly created quote’s checkbox. From the actions select “Create PDF of Quote” to generate a pdf of this new quote.
Create Your First Invoice¶
This is going to be a very short chapter because all you have to do is repeat the steps above but instead of selecting “Create Quote” in the Contract Actions list you select “Create Invoice”; alternatively by selecting your new Quote and use the action “Create Invoice”. The second way is much easier and faster because the program just takes all values and positions from the quote and transforms it into a invoice.
Accounting¶
Accouting Periods¶
An Accounting Period is the timeframe over which you make your Profit and Loss calculation. Its often called Fiscal Year, Business Year or Business Quarter. What ever you like. Accounting Periods have nothing to do with the Accounts but with the Bookings. When you open an existing Accounting Period you find a list of all Bookings during the period below as an inline table on the page. Feel free to add your bookings here. Be careful when you set up a new Accounting Period - koalixcrm does not check if you create bookings that are outside the possible Accounting Period range nor does it check if there are two accounting periods for the same time period. It is up to the user to check that.
Account section¶
Is a Customer Payment Account¶
These are the accounts you are able to select when you choose “register payment” in your invoice detail view as destinations for Customers to pay into.
Is the Open Liabilities Account¶
This is not implemented yet because the link between Accounting and CRM is not yet finised for the purchase order side (where you were buying not selling). This is usually not used by companies because its to much effort to copy all the invoices they receive from suppliers into your system. Normally you will only book this manually and store the invoice you got from your supplier physically in a filer in your office. If you do so think about using a good description so that you find the invoice in case of a tax audit (I have never had a tax audit in my company but I think they are really interested in such things :-) ).
Is the Open Intrest Account¶
There should only be one Open Intrest Account in your Accounting and it is used to book invoiced contract amounts. You will have to set this open intrest account. If this is not set on at least one account the link between Accounting and CRM will not work correctly.
Is a Product Inventory Account¶
You may choose this option but it has no effect yet because Product inventory is not yet implemented.
Bookings¶
A booking is a common part of all accounting. Link to wikipage.
Product Categories¶
Product Categories are needed for the interface between the CRM and Accounting. You can introduce different product Categories for different kinds of companies. In this example, we have an “IT support company”. An IT Support company usually provides Support and Hardware. Support can be for on-site support or in-house support. Its possible that the support must be bought from an other company because you were not able to do everything yourself. Then the Hardware, you normally don’t produce hardware on your own, you buy them from a supplier.
Now lets record that as the following products you may offer to your customers.
| Product Nr. | Description |
| 1 2 3 4 | in-house work on-site work computer hardware voip hardware |
To be able to do automatic accounting you will have to set the accounts where you want to book your income and spending for each product.
| Product Nr. | Earnings Acc. | Spendings Acc. |
| 1. 2. 3. 4. | Income Support Income Support Income Hardware Income Hardware | Spending Support from third Spending Support from third Spendings Hardware Spendings Hardware |
Of course, there are more than four products in your inventory - I hope - and depending on your “love of details” you will have hundreds of them. Instead of setting the Earnings and Spendings Accounts for every Product individually koalixcrm has useful product categories where you only have to set it once. After that you are able to link the product categories when you add a product in your CRM. Its also possible to leave this blank if you don’t want to make the link between CRM and Accounting
Django User Extension¶
Introduction¶
The Django Framework supports some basic users, authentication and group permissions. This is OK for most Django apps but in koalixcrm some additional information about users is needed. To be able to generate PDF’s we need some information about the user that is generating the documents. There are some obvious fields like the internal phone number that are printed on every document - if you like. But there are also some “behind the scenes” fields needed. In this chapter I describe all of them in a bit more detail.
If you are administrator of the koalixcrm instance: It is recommended that you give add/modify access for this user-extension only yourself and/or your boss. Users of koalixcrm really don’t need to get access to this part of koalixcrm
FOP PDF Creation¶
Before I start describing how you can set up the User Extension, this short section will explain to you what is going on when you create PDF’s.
In koalixcrm you are able to set up and store contracts with invoices, quotes and so on. This is quite cool but worthless when you have no ability to print them for your customers. This is the point where it starts to become difficult in django … and of course also in most other frameworks, the export of data is a little bit difficult. For Django most people prefer using ReportLab, but not in koalixcrm for the following reasons:
- The ReportLab input files are not in a common format.
- It does not seem to be very open … and I don’t like that.
- It doesn’t seem its built for creating letters
Now all these requirements are fully covered by an other PDF creation tool: apache-fop. All would be perfect if apache-fop wasn’t programmed in JAVA.
Anyway, for now koalixcrm uses apache-fop to create PDF’s and there is no plan to change that until I run into huge problems.
How does this work:
1. When you select “Create PDF of Invoice” in the actions list of your invoice, a XML file of all the Django objects is created in the /tmp folder of your system
2. Now Django executes an os.check_output command, “fop -c (configurationfile) -xml (the createdxmlfile) -xsl (your xsl file) -pdf (the output pdf file)”
- If the command creates any error you will see the full traceback in the front-end.
As you can see there are several files needed to get from a xml to a pdf. These files can be stored in the TemplateSet of the UserExtension-Part of koalixcrm. You can define as many different TemplateSets you like. This makes sense because sometimes you want different users having different pdf styles or you want to be able to access an old style because a new one has an bug.
Object types¶
User Extensions¶
The Users Extension is a container for all kind of Information that is needed to create a PDF with user specific information in it.
XSL Files¶
TemplateSet¶
As described in the first part of this chapter the templateset is the place where you compose a template style set for users. Templatesets are refered in the UserExtension and must be set in order to be able to create PDFs. A TemplateSet consists of following parts:
- Invoice XSL File
- Quote XSL File
- Purchase Order XSL File
- Purchase Confirmation XSL File
- Delivery Order XSL File
A TemplateSet is a set of xsl-templatefiles, Header and Footer Texts. A starting TemplateSet is installed by the command ./manage koalixcrm_install_defaulttemplates but you can also define and install your own xsl files by setting up your own templateset and selecting it in the user Extension of your own user.
Customising koalixcrm¶
There are several ways in which to customise koalixcrm, depending on your requirements.
In all cases contributions can be submitted back to koalixcrm by opening an issue in GitHub - see our repositories CONTRIBUTING.md file for more information.
Translators¶
The Application itself¶
To translate the application itself the only thing you have to do is to install koalixcrm on a Linux or Windows Machine. Please excuse that I can’t give you good advice in how to install the software under Windows I simply do not have the nerves to play around with the Windows powershell or the cmd :-).
cd /var/www/koalixcrm/crm
django-admin makemessages -l yourlanguage
this creates a new directory in the folder called /var/www/koalixcrm/crm/locale/yourlanguage/LC_MESSAGES/
in this directory you will find one file called django.po - edit this file in the following way:
Lets say you want to translate koalixcrm to French. Find all msgid’s in django.po and look at the english text. The msgstr following a msgid will be the place you write your translation.
- Example::
- msgid “phonenumber” msgstr “phonenumber”
- Adjust it to the following::
- msgid “phonenumber” msgstr “nombre de telefon”
After you finised translating the whole file test your translation by compiling it.
django-admin compilemessages
After this you are able to use your translation. Sometimes seting your language in /var/www/koalixcrm/settings.py is required.
Go on with your translation for accounting and for djangouserextention folders.
As soon as you finish this part you will be able to work with koalixcrm in your own language. But there is still something missing: the templatefiles for pdf creation have to be translated as well.
Custom template files for PDF creation¶
For translators or localisers¶
To translate the templatefiles for PDF creation you will have to adjust the templatefiles in the /var/www/koalixcrm/templatefiles folder. There you will find a folder for every language code that is already
translated by the koalixcrm comunity or me. To add your own language type the following:
cp -R en yourlanguage
now open yourlanguage folder and adjust the content of every xml file.
Site specific customisation¶
As with customisations for translators, the focus for site specific customisation is koalixcrm’s install path/templatefiles/yourlanguage. Entries in the yourlanguage folder can be edited as you wish, to produce documents with your letterhead, contact details or other modifications.
Modders¶
There is currently no API available … I’m going to start with that as soon as possible but certainly after I finish the rest of the user documentation.
