contacts
: Managing contacts¶
The contacts
plugin adds functionality for managing your contacts. It
defines concepts like partner, person and organization.
Concepts¶
- business partner¶
Any person or organization for which you want to keep contact data like postal address, phone number, etc.
A business partner can act as the recipient of a sales invoice, as the sender of a purchase invoice, … A partner has at least a name and usually also an address.
Represented by
Partner
.- partner¶
Shortcut for business partner.
A business partner is always either a (natural) person or an organization.
- 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
. They are stored using thePerson
database model.- organization¶
A corporation, company, organization, family or any other potential business partner that is not a person.
You can see the organizations in your database via
.
Note how persons and organizations have similarities and differences. For example they all have an address and a phone number field. But persons have a e.g. Last name, First name and Sex fields while organizations have an Organization type field.
The Partners table is what persons and organizations have in common. As you can see, this table contains both your persons and your organizations together in a same list. It is the union of both tables.
Why do we need such a union table of business partners? For example an invoice (one of the important documents used in accounting) must have a recipient, and that recipient can be a private person for some invoices and an organization for some other invoices. And (last but not least) in many accounting situations you are not interested whether it’s a person or an organizations, it is just some business partner who owes you money.
Lino applications can add additional types of business partners: households, employees, patients, beneficiaries, teachers, shareholders, …
Linking persons and organizations¶
A person can have a given role in a given organization and thus becomes a contact person.
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 window shows the contact persons of this organization. The Is contact for panel of a person’s detail window 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()
.
Database models¶
- class lino_xl.lib.contacts.Partner¶
The database model used to represent a business partner.
- 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 thename
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.
- 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 of this business partner.
This field exists only when
lino_xl.lib.ledger
is installed, which uses it as theinvoice_account_field_name
forTradeTypes.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¶
The database model used to represent a person.
- first_name¶
- last_name¶
- gender¶
- name¶
See
Partner.name
.
- class lino_xl.lib.contacts.Company¶
The database 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.Role¶
The database 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 function in this organization.
This field is a learning foreign key: if you type the name of a person that does not yet exist in the database, Lino creates it silently.
- 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 database 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.
Table views¶
- class lino_xl.lib.contacts.Companies¶
Base table for all tables showing companies.
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.
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.
- contact_role¶
The optional
Role
of thecontact_person
withincompany
.
- partner¶
(Virtual field) The “legal partner”, i.e. usually the
company
, except when that field is empty, in which case partner contains thecontact_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 thecompany
orcontact_person
(if one of these fields is non-empty). It may also be alino_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. aRole
object), but accountants want to know the juristic person, which is either thecompany
or a privateperson
(if nocompany
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>
andlino_tera.lib.tera.Client>
andlino_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
Setting the site operator¶
Check whether you want Lino to know who is the site operator. For example when you issue a sales invoice, Lino will use this to print your address and contact data on the invoice. See How to specify the site operator.