`finan` : Financial vouchers¶

This document describes the lino_xl.lib.finan plugin, which introduces concepts like financial voucher and booking suggestion.

A tested document
Vocabulary
Payment orders
Bank statements
Cash journals
Journal entries
Model mixins
Plugin configuration
Tables
Booking suggestions
Template files

A tested document ¶

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

>>> from lino import startup
>>> startup('lino_book.projects.apc.settings.doctests')
>>> from lino.api.doctest import *
>>> ses = rt.login("robin")
>>> translation.activate('en')

This document is based on the following other specifications:

Vocabulary ¶

There are three kinds of financial vouchers:

bank statement

A ledger voucher received from your bank and which reports the transactions that occurred on a given bank account during a given period.

See Bank statements.

payment order

A voucher you send to your bank asking them to execute a series of payments (outgoing transactions) to third-party partners from a given bank account.

See Payment orders.

journal entry

A voucher where you declare that you move money around internally, for your own accounting.

French: "operations diverse".

See Journal entries.

financial voucher

General term for the voucher types bank statement, payment order and journal entry. They have certain things in common, but use different database models because certain things differ.

expected movement

A ledger movement that did not yet happen but is expected to happen. For example the payment of an invoice.

booking suggestion

A suggestion to add an expected movement to a financial voucher. See Booking suggestions.

Payment orders ¶

To configure a journal of payment orders, you set the following fields:

voucher_type should be lino_xl.lib.ledger.VoucherTypes.bank_po
partner ("Organization") should point to your bank.
dc (Primary booking direction) should be DEBIT because each item should debit (not credit) the partner's account.
account should be the ledger account marked as CommonAccounts.pending_po.

A payment order clears the invoices it asks to pay. Which means for example that a supplier might tell you that some invoice isn't yet paid, although your MovementsByPartner says that it is paid. The explanation for this difference is simply that the payment order hasn't yet been executed by your or their bank.

Lino books the sum of a payment order into a single counter-movement that will debit your bank's partner account (specified in the partner of the journal). Your bank becomes a creditor (you owe them the sum of the payments) and you expect this amount to be cleared by an expense in a bank statement which confirms that the bank executed your payment order.

>>> rt.show("finan.PaymentOrdersByJournal", ledger.Journal.get_by_ref("PMO"))
===================== ============ =========== =============== ================ =================== ================
 No.                   Entry date   Narration   Total           Execution date   Accounting period   Workflow
--------------------- ------------ ----------- --------------- ---------------- ------------------- ----------------
 2/2015                13/02/2015               6 801,22                         2015-02             **Registered**
 1/2015                13/01/2015               5 626,48                         2015-01             **Registered**
 12/2014               13/12/2014               5 878,16                         2014-12             **Registered**
 11/2014               13/11/2014               6 124,29                         2014-11             **Registered**
 10/2014               13/10/2014               5 877,47                         2014-10             **Registered**
 9/2014                13/09/2014               6 228,18                         2014-09             **Registered**
 8/2014                13/08/2014               5 707,66                         2014-08             **Registered**
 7/2014                13/07/2014               5 944,37                         2014-07             **Registered**
 6/2014                13/06/2014               6 112,07                         2014-06             **Registered**
 5/2014                13/05/2014               6 350,89                         2014-05             **Registered**
 4/2014                13/04/2014               7 061,63                         2014-04             **Registered**
 3/2014                13/03/2014               5 570,88                         2014-03             **Registered**
 2/2014                13/02/2014               5 570,38                         2014-02             **Registered**
 1/2014                13/01/2014               6 793,62                         2014-01             **Registered**
 **Total (14 rows)**                            **85 647,30**
===================== ============ =========== =============== ================ =================== ================

class lino_xl.lib.finan.PaymentOrder¶

Django model to represent a payment order.

entry_date¶: The date of the ledger entry.

execution_date¶: The execution date of payment order. If this is empty, Lino assumes the entry_date when writing the pain_001.xml file.

total¶: The total amount. This is automatically computed when you register de voucher.

class lino_xl.lib.finan.PaymentOrderItem¶: Django model to represent an individual item of a payment order.

class lino_xl.lib.finan.PaymentOrders¶: The base table of all tables on PaymentOrder.

class lino_xl.lib.finan.ItemsByPaymentOrder¶

Bank statements ¶

>>> rt.show("finan.BankStatementsByJournal", ledger.Journal.get_by_ref("BNK"))
===================== ============ =============== =============== =================== ================
 No.                   Entry date   Old balance     New balance     Accounting period   Workflow
--------------------- ------------ --------------- --------------- ------------------- ----------------
 2/2015                21/02/2015   -2 367,73       -1 723,45       2015-02             **Registered**
 1/2015                21/01/2015   2 518,58        -2 367,73       2015-01             **Registered**
 12/2014               21/12/2014   1 732,80        2 518,58        2014-12             **Registered**
 11/2014               21/11/2014   2 377,98        1 732,80        2014-11             **Registered**
 10/2014               21/10/2014   -2 395,03       2 377,98        2014-10             **Registered**
 9/2014                21/09/2014   -5 619,22       -2 395,03       2014-09             **Registered**
 8/2014                21/08/2014   -2 029,93       -5 619,22       2014-08             **Registered**
 7/2014                21/07/2014   -190,86         -2 029,93       2014-07             **Registered**
 6/2014                21/06/2014   5 846,85        -190,86         2014-06             **Registered**
 5/2014                21/05/2014   -524,23         5 846,85        2014-05             **Registered**
 4/2014                21/04/2014   -2 746,54       -524,23         2014-04             **Registered**
 3/2014                21/03/2014   288,24          -2 746,54       2014-03             **Registered**
 2/2014                21/02/2014   1 196,16        288,24          2014-02             **Registered**
 1/2014                21/01/2014                   1 196,16        2014-01             **Registered**
 **Total (14 rows)**                **-1 912,93**   **-3 636,38**
===================== ============ =============== =============== =================== ================

class lino_xl.lib.finan.BankStatement¶

Django model to represent a bank statement.

balance1¶: The old (or start) balance.

balance2¶: The new (or end) balance.

class lino_xl.lib.finan.BankStatementItem¶: Django model to represent an individual item of a bank statement.

class lino_xl.lib.finan.BankStatements¶: The base table of all tables on BankStatement.

class lino_xl.lib.finan.ItemsByBankStatement¶: Shows the items of a bank statement.

Cash journals ¶

Cash journals are technically the same as bank statements.

>>> rt.show("finan.BankStatementsByJournal", ledger.Journal.get_by_ref("CSH"))
No data to display

Journal entries ¶

>>> rt.show("finan.JournalEntriesByJournal", ledger.Journal.get_by_ref("MSC"))
No data to display

>>> rt.show("finan.JournalEntriesByJournal", ledger.Journal.get_by_ref("PRE"))
======== ============ =========== =================== ================
 No.      Entry date   Narration   Accounting period   Workflow
-------- ------------ ----------- ------------------- ----------------
 1/2014   01/01/2014               2014-01             **Registered**
======== ============ =========== =================== ================

class lino_xl.lib.finan.JournalEntry¶: Django model to represent a journal entry.

class lino_xl.lib.finan.JournalEntryItem¶: Django model to represent an individual item of a journal entry.

class lino_xl.lib.finan.JournalEntries¶: The base table of all tables on JournalEntry.

class lino_xl.lib.finan.ItemsByJournalEntry¶: Shows the items of a journal entry.

Model mixins ¶

class lino_xl.lib.finan.FinancialVoucher¶

Base class for all financial vouchers.

item_account¶: The default value to use when FinancialVoucherItem.account of an item is empty.

item_remark¶: The default value to use when FinancialVoucherItem.remark of an item is empty.

printed¶
See :attr:`lino_xl.lib.excerpts.mixins.Certifiable.printed`

class lino_xl.lib.finan.FinancialVoucherItem¶

The base class for the items of all types of financial vouchers (FinancialVoucher).

account¶: The general account to be used in the primary booking. If this is empty, use item_account of the voucher.

project¶: The "project" related to this transaction. For example in Lino Welfare this is the client.

partner¶

The partner account to be used in the primary booking.

In Lino Welfare this field is optional and used only for transactions whose recipient is different from the client. When empty, Lino will book to the client (i.e. project).

amount¶: The amount to be booked. If this is empty, then the voucher cannot be registered.

dc¶: The direction of the primary booking to create.

remark¶: External reference. The description of this transation as seen by the external partner.

seqno¶

match¶

An arbitrary string used to group several movements.

A reference to the voucher that caused this voucher entry. For example the match of the payment of an invoice points to that invoice.

In a bank statement you might want to specify an individual date for every item.

class lino_xl.lib.finan.DatedFinancialVoucher¶: A FinancialVoucher whose items have a date field.

class lino_xl.lib.finan.DatedFinancialVoucherItem¶

A FinancialVoucherItem with an additional date field.

date¶: The value date of this item.

Plugin configuration ¶

class lino_xl.lib.finan.Plugin¶

This Plugin class adds some entries to the Explorer menu. It contains the following additional attributes:

suggest_future_vouchers¶

Whether to suggest vouchers whose due_date is in the future.

The default value is currently False because some demo fixtures rely on this. But in most cases this should probably be set to True because of course a customer can pay an invoice in advance.

You can specify this for your application:

def setup_plugins(self):
    self.plugins.finan.suggest_future_vouchers = True
    super(Site, self).setup_plugins()

Or, as a local system administrator you can also simply set it after your SITE instantiation:

SITE = Site(globals())
...
SITE.plugins.finan.suggest_future_vouchers = True

Tables ¶

class lino_xl.lib.finan.FinancialVouchers¶: Base class for the default tables of all financial voucher types (JournalEntries , PaymentOrders and BankStatements).

class lino_xl.lib.finan.ItemsByVoucher¶: The base table of all tables which display the items of a given voucher.

Booking suggestions ¶

In a financial voucher you often book transactions that are actually expected. When you have booked your invoices, then Lino "knows" that each invoice will --ideally-- lead to a payment.

class lino_xl.lib.finan.SuggestionsByVoucher¶

Shows the suggested items for a given voucher, with a button to fill them into the current voucher.

This is the base class for SuggestionsByJournalEntry SuggestionsByBankStatement and SuggestionsByPaymentOrder who define the class of the master_instance (master)

This is an abstract virtual slave table.

Every row is a DueMovement object.

class lino_xl.lib.finan.SuggestionsByJournalEntry¶: A SuggestionsByVoucher table for a JournalEntry.

class lino_xl.lib.finan.SuggestionsByPaymentOrder¶: A SuggestionsByVoucher table for a PaymentOrder.

class lino_xl.lib.finan.SuggestionsByBankStatement¶: A SuggestionsByVoucher table for a BankStatement.

class lino_xl.lib.finan.SuggestionsByVoucherItem¶: Displays the payment suggestions for a given voucher item, with a button to fill them into the current item (creating additional items if more than one suggestion was selected).

class lino_xl.lib.finan.SuggestionsByJournalEntryItem¶

class lino_xl.lib.finan.SuggestionsByPaymentOrderItem¶: A SuggestionsByVoucherItem table for a PaymentOrderItem.

class lino_xl.lib.finan.SuggestionsByBankStatementItem¶: A SuggestionsByVoucherItem table for a BankStatementItem.

class lino_xl.lib.finan.ShowSuggestions¶: Show suggested items for this voucher.

class lino_xl.lib.finan.FillSuggestionsToVoucher¶

Fill selected suggestions from a SuggestionsByVoucher table into a financial voucher.

This creates one voucher item for each selected row.

class lino_xl.lib.finan.FillSuggestionsToVoucherItem¶: Fill the selected suggestions as items to the voucher. The first selected suggestion does not create a new item but replaces the item for which it was called.

Template files ¶

pain_001.xml¶

Used for writing a SEPA payment initiation.

finan/PaymentOrder/pain_001.xml

class lino_xl.lib.finan.FinancialVoucherItemChecker¶

finan : Financial vouchers¶

`finan` : Financial vouchers¶