`contacts` : Managing contacts¶

The lino_xl.lib.contacts plugin adds functionality for managing contacts. It adds the concepts of "partners", "persons", "organizations" and "contact roles".

A tested document
Database structure
Menu entries
Dependencies
Concepts
The site operator
Models and views
Quick search
Numeric quick search
Quickly finding a partner using its primary key
Exporting contacts as vcard files
User roles
Filtering partners
Other models
Model mixins
Print templates
Civil state
Automatically creating contact persons

A tested document ¶

This is a tested document. The following instructions are used for initialization:

>>> import lino
>>> lino.startup('lino_book.projects.min1.settings.doctests')
>>> from lino.api.doctest import *
>>> from django.db.models import Q

Database structure ¶

This plugin defines the following database models.

The main models are Person and Company and their common base Partner.
A RoleType ("Function") where you can configure the available functions.
A CompanyType model can be used to classify organizations.

TODO: rename "RoleType" to "Function" or "ContactType"?

Dependencies ¶

This plugin needs lino_xl.lib.countries and lino.modlib.system.

This plugin is being extended by Lino Welfare in lino_welfare.modlib.contacts or by Lino Voga in lino_voga.modlib.contacts.

A partner can act as the recipient of a sales invoice, as the sender of an incoming purchases invoice, ... A partner has at least a name and usually also an address. A partner is never "just a partner", it is always either a (natural) person or an organization.

partner

Any person or organization for which you want to keep contact data like postal address, phone number, etc. Represented by Partner.

person

A natural human person with a gender, first and last name. See also The Human mixin.

You can see the persons in your database via Contacts ‣ Persons. They are stored using the Person database model.

organization

A corporation, company, organization, family or any other potential partner that is not a person.

You can see the organizations in your database via Contacts ‣ Organizations. They are stored using the Company database model.

A contact person is when a given person exercises a given function in a given organization. A contact function is what a given person can exercise in a given organization.

contact person

The fact that a given person exercises a given function within a given organization.

The Contact persons panel of an organization's detail view shows the contact persons of this organization. The Is contact for panel of a person's detail view shows the organizations where this person exercises a function.

Contact person entries are stored using the Role database model.

contact function

A function that a person can exercise in an organization. Represented by RoleType.

signer function

A contact function that has can_sign set to True.

A contact person exercising a signer function is allowed to sign business documents. See Partner.get_signers().

The demo database defines the following contact functions:

>>> rt.show(contacts.RoleTypes)
==== ============= ================== ===================== ====================
 ID   Designation   Designation (de)   Designation (fr)      Authorized to sign
---- ------------- ------------------ --------------------- --------------------
 1    CEO           Geschäftsführer    Gérant                Yes
 2    Director      Direktor           Directeur             Yes
 3    Secretary     Sekretär           Secrétaire            No
 4    IT manager    EDV-Manager        Gérant informatique   No
 5    President     Präsident          Président             Yes
==== ============= ================== ===================== ====================

The site operator ¶

When this plugin is installed, the site manager usually creates a Company that represents the site operator, and have the field SiteConfig.site_company point to it.

>>> siteop = settings.SITE.site_config.site_company
>>> siteop.__class__
<class 'lino_xl.lib.contacts.models.Company'>

>>> print(siteop)
Rumma & Ko OÜ

>>> for obj in siteop.get_signers():
...     print("{}, {}".format(obj.person.get_full_name(), obj.type))
Mrs Erna Ärgerlich, CEO

Models and views ¶

class lino_xl.lib.contacts.Partner¶

The Django model used to represent a partner.

The contacts plugin defines two subclasses of Partner: Person and Company. Applications can define other subclasses for Partner. On the other hand, the Partner model is not abstract, i.e. you can see a table where persons and organizations are together. This is useful e.g. in accounting reports where all partners are handled equally, without making a difference between natural an legal persons.

name¶

The full name of this partner. Used for alphabetic sorting.

Subclasses may hide this field and fill it automatically. For example on a Person, Lino automatically sets the name field to <last_name>, <first_name>, and the field is usually hidden for end users.

prefix¶

An optional name prefix. For organisations this is inserted before the name, for persons this is inserted between first name and last name.

See lino.mixins.human.Human.get_last_name_prefix().

email¶: The primary email address.

phone¶

The primary phone number.

Note that Lino does not ignore formatting characters in phone numbers when searching. For example, if you enter "087/12.34.56" as a phone number, then a search for phone number containing "1234" will not find it.

gsm¶: The primary mobile phone number.

language¶: The language to use when communicating with this partner.

purchase_account¶

The general account to suggest as default value in purchase invoices from this partner.

This field exists only when lino_xl.lib.ledger is installed, which uses it as the invoice_account_field_name for TradeTypes.purchases.

Two fields exist only when lino_xl.lib.vat is installed:

vat_regime¶: The default VAT regime to use on invoices for this partner.

vat_id¶: The national VAT identification number of this partner.

class lino_xl.lib.contacts.Partners¶

detail_layout¶

The detail layout of the Partners table is not set by default. Especially accounting applications will set it to 'contacts.PartnerDetail'.

That's because the Partners view that shows companies and persons merged together is useful only for certain accounting reports.

class lino_xl.lib.contacts.Person¶

Django model used to represent a person.

first_name¶

last_name¶

gender¶

name¶: See Partner.name.

class lino_xl.lib.contacts.Persons¶: Shows all persons.

class lino_xl.lib.contacts.Company¶

Django model used to represent an organization.

The verbose name is "Organization" while the internal name is "Company" because that's easier to type and for historical reasons.

type¶: Pointer to the CompanyType.

The following fields are defined in the base model Partner, they are what companies and persons have in common:

name¶

street¶

gsm¶

phone¶

get_signers(today=None)¶

Return an iterable over the contact persons who can sign business documents (i.e. exercise a signer function) for this organization.

If today is specified and with_roles_history is True, return only the contact persons that were exercising a signer function at the given date.

contact person represents a person that signs contracts, invoices or other business documents for the site operator.

class lino_xl.lib.contacts.Companies¶: Base table for all tables showing companies.

class lino_xl.lib.contacts.Role¶

The Django model used to represent a contact person.

company¶: The organization where this person has this role.

type¶: The function of this person in this organization.

person¶

The person having this role in this organization.

This is a learning foreign key. See Automatically creating contact persons

start_date¶

When this person started to exercise this function in this organization.

This is a dummy field when Plugin.with_roles_history is False.

end_date¶

When this person stopped to exercise this function in this organization.

This is a dummy field when Plugin.with_roles_history is False.

class lino_xl.lib.contacts.RoleType¶

The Django model used to represent a contact function.

name¶: A translatable designation. Used e.g. in document templates for contracts.

can_sign¶: Whether this is a signer function.

Quick search ¶

When doing a quick search in a list of partners, Lino searches only the name field and not for example the street.

>>> rt.show(contacts.Partners, quick_search="berg")
==================== ===== =========================== ================
 Name                 ID    See as                      e-mail address
-------------------- ----- --------------------------- ----------------
 Altenberg Hans       114   Organization, **Partner**
 Garage Mergelsberg   104   **Partner**, Person
==================== ===== =========================== ================

Without that restriction, a user who enters "berg" in the quick search field would also get e.g. the following partners (because their address contains the query string):

>>> rt.show(contacts.Partners, column_names="name street",
...     filter=Q(street__icontains="berg"))
===================== ===================
 Name                  Street
--------------------- -------------------
 Bastiaensen Laurent   Am Berg
 Collard Charlotte     Auf dem Spitzberg
 Ernst Berta           Bergkapellstraße
 Evers Eberhart        Bergstraße
 Kaivers Karl          Haasberg
 Lazarus Line          Heidberg
===================== ===================

This behaviour is implemented using the quick_search_fields attribute on the model.

>>> contacts.Partner.quick_search_fields
(<django.db.models.fields.CharField: prefix>, <django.db.models.fields.CharField: name>, <django.db.models.fields.CharField: phone>, <django.db.models.fields.CharField: gsm>)

Numeric quick search ¶

You can search for phone numbers

>>> rt.show(contacts.Partners, quick_search="123", column_names="name phone id")
====================== ============== =====
 Name                   Phone          ID
---------------------- -------------- -----
 Arens Andreas          +32 87123456   112
 Arens Annette          +32 87123457   113
 Dobbelstein Dorothée                  123
====================== ============== =====

Quickly finding a partner using its primary key ¶

A special type of quick search is when the search string starts with "#". In that case you get the partner with that primary key.

>>> rt.show(contacts.Partners, quick_search="#123", column_names="name phone id")
====================== ======= =====
 Name                   Phone   ID
---------------------- ------- -----
 Dobbelstein Dorothée           123
====================== ======= =====

This behaviour is the same for all subclasses of Partner, e.g. for persons and for organizations.

>>> rt.show(contacts.Persons, quick_search="berg")
=================== ============================= ================ ======= ===== ===== ==========
 Name                Address                       e-mail address   Phone   GSM   ID    Language
------------------- ----------------------------- ---------------- ------- ----- ----- ----------
 Mr Hans Altenberg   Aachener Straße, 4700 Eupen                                  114
=================== ============================= ================ ======= ===== ===== ==========

>>> rt.show(contacts.Companies, quick_search="berg")
==================== ============================= ================ ======= ===== ===== ==========
 Name                 Address                       e-mail address   Phone   GSM   ID    Language
-------------------- ----------------------------- ---------------- ------- ----- ----- ----------
 Garage Mergelsberg   Hauptstraße 13, 4730 Raeren                                  104
==================== ============================= ================ ======= ===== ===== ==========

Exporting contacts as vcard files ¶

class lino_xl.lib.contacts.ExportVCardFile¶

Download all records as a .vcf file which you can import to another contacts application.

This action exists on every list of partners when your application has use_vcard_export set to True.

User roles ¶

class lino_xl.lib.contacts.SimpleContactsUser¶: A user who has access to basic contacts functionality.

class lino_xl.lib.contacts.ContactsUser¶: A user who has access to full contacts functionality.

class lino_xl.lib.contacts.ContactsStaff¶: A user who can configure contacts functionality.

Filtering partners ¶

class lino_xl.lib.contacts.PartnerEvents¶

A choicelist of observable partner events.

has_open_movements¶: See Filtering partners regarding ledger movements in ledger: General accounting. This choice exists only when lino_xl.lib.ledger is installed.

Other models ¶

class lino_xl.lib.contacts.CompanyTypes¶

class lino_xl.lib.contacts.CompanyType¶: A type of organization. Used by Company.type field.

Model mixins ¶

class lino_xl.lib.contacts.ContactRelated¶

Model mixin for things that relate to either a private person or a company, the latter potentially represented by a contact person having a given role in that company. Typical usages are invoices or contracts.

Adds 3 database fields and two virtual fields.

company¶: Pointer to Company.

contact_person¶: Pointer to Person.

contact_role¶: The optional Role of the contact_person within company.

partner¶: (Virtual field) The "legal partner", i.e. usually the company, except when that field is empty, in which case partner contains the contact_person. If both fields are empty, then partner contains None.

recipient¶: (Virtual field) The Addressable object to use when printing a postal address for this. This is typically either the company or contact_person (if one of these fields is non-empty). It may also be a lino_xl.lib.contacts.models.Role object.

Difference between partner and recipient: an invoice can be issued and addressed to a given person in a company (i.e. a Role object), but accountants want to know the juristic person, which is either the company or a private person (if no company specified), but not a combination of both.

class lino_xl.lib.contacts.PartnerDocument¶: Deprecated. Adds two fields 'partner' and 'person' to this model, making it something that refers to a "partner". person means a "contact person" for the partner.

Print templates ¶

contacts/Person/TermsConditions.odt¶: Prints a "Terms & Conditions" document to be used by organisations who need a signed permission from their clients for storing their contact data. The default content may be localized.

Civil state ¶

>>> from lino_xl.lib.contacts.choicelists import CivilStates
>>> show_choicelist(CivilStates)
======= ==================== ==================== ============================= =============================
 value   name                 en                   de                            fr
------- -------------------- -------------------- ----------------------------- -----------------------------
 10      single               Single               Ledig                         célibataire
 20      married              Married              Verheiratet                   marié
 30      widowed              Widowed              Verwitwet                     veuf/veuve
 40      divorced             Divorced             Geschieden                    divorcé
 50      separated            Separated            Getrennt von Tisch und Bett   Séparé de corps et de biens
 51      separated_de_facto   De facto separated   Faktisch getrennt             Séparé de fait
 60      cohabitating         Cohabitating         Zusammenwohnend               Cohabitant
======= ==================== ==================== ============================= =============================

class lino_xl.lib.contacts.CivilStates¶

The global list of civil states that a person can have. The field pointing to this list is usually named civil_state.

Usage examples are lino_welfare.modlib.pcsw.models.Client> and lino_tera.lib.tera.Client> and lino_avanti.lib.avanti.Client> .

The four official civil states according to Belgian law are:

single¶: célibataire : vous n’avez pas de partenaire auquel vous êtes officiellement lié

married¶: marié(e) : vous êtes légalement marié

widowed¶: veuf (veuve) / Verwitwet : vous êtes légalement marié mais votre partenaire est décédé

divorced¶: divorcé(e) (Geschieden) : votre mariage a été juridiquement dissolu

Some institutions define additional civil states for people who are officially still married but at different degrees of separation:

de_facto_separated¶

De facto separated (Séparé de fait, faktisch getrennt)

Des conjoints sont séparés de fait lorsqu'ils ne respectent plus le devoir de cohabitation. Leur mariage n'est cependant pas dissous.

La notion de séparation de fait n'est pas définie par la loi. Toutefois, le droit en tient compte dans différents domaines, par exemple en matière fiscale ou en matière de sécurité sociale (assurance maladie invalidité, allocations familiales, chômage, pension, accidents du travail, maladies professionnelles).

separated¶

Legally separated, aka "Separated as to property" (Séparé de corps et de biens, Getrennt von Tisch und Bett)

La séparation de corps et de biens est une procédure judiciaire qui, sans dissoudre le mariage, réduit les droits et devoirs réciproques des conjoints. Le devoir de cohabitation est supprimé. Les biens sont séparés. Les impôts sont perçus de la même manière que dans le cas d'un divorce. Cette procédure est devenue très rare.

Another unofficial civil state (but relevant in certain situations) is:

cohabitating¶

Cohabitating (cohabitant, zusammenlebend)

Vous habitez avec votre partenaire et c’est reconnu légalement.

Sources for above: belgium.be, gouv.qc.ca, wikipedia.org

Automatically creating contact persons ¶

The Role.person field in the RolesByCompany table is a learning foreign key field: if you type the name of a person that does not yet exist in the database, Lino creates it silently.

Some examples of how the name is parsed when creating a person:

>>> pprint(rt.models.contacts.Person.choice_text_to_dict("joe smith"))
{'first_name': 'Joe', 'last_name': 'Smith'}

>>> pprint(rt.models.contacts.Person.choice_text_to_dict("Joe W. Smith"))
{'first_name': 'Joe W.', 'last_name': 'Smith'}

>>> pprint(rt.models.contacts.Person.choice_text_to_dict("Joe"))
Traceback (most recent call last):
...
django.core.exceptions.ValidationError: ['Cannot find first and last name in "Joe"']

>>> pprint(rt.models.contacts.Person.choice_text_to_dict("Guido van Rossum"))
{'first_name': 'Guido', 'last_name': 'van Rossum'}

The algorithm has already some basic intelligence but plenty of growing potential...

`contacts` : Managing contacts¶

A tested document ¶

Database structure ¶

Menu entries ¶

Dependencies ¶

Concepts ¶

The site operator ¶

Models and views ¶

Quick search ¶

Numeric quick search ¶

Quickly finding a partner using its primary key ¶

Exporting contacts as vcard files ¶

User roles ¶

Filtering partners ¶

Other models ¶

Model mixins ¶

Print templates ¶

Civil state ¶

Automatically creating contact persons ¶

contacts : Managing contacts¶

`contacts` : Managing contacts¶