What's new in LedgerSMB 1.8

• Authentication and session storage using encrypted cookies
• In-database logos and images upload and template support
• Downloadable reports now stored in the database for customization
• New e-mail configuration in ledgersmb.conf
• Reconciliation takes payments as first-order transactions
• Import of OFX bank statement files for reconciliation

When upgrading from 1.6 or older, please read the 1.7 release notes.

New features

Authentication and session storage using encrypted cookies

This release switches to using encrypted cookies instead of HTTP's Basic auth facility. This switch has simplified the authentication code paths and eliminates the browser authentication popups on expired sessions or incorrect configurations. Using cookie authentication also allows more consistent destruction of session data on various browsers.

In order to encrypt the session data in the cookie, a secret is generated on the server each time the server process is restarted. This means that restarting the server process immediately invalidates all active sessions. To prevent this, set the "cookie_secret" configuration value in ledgersmb.conf to something random and sufficiently long (50 or more characters).

In-database logos and images upload and template support

With this release, it's now possible to upload documents (e.g. images or logos) to the database through a new menu "System > Files". These in-database documents can then be included in templates. This release adds 3 new functions, available to templates, each with its own use:

• dbfile_path("name-of-file-in-database")
  This function can be used in a LaTeX document as:  \includegraphics{<?lsmb dbfile_path("name-of-file-in-database") ?>}. The function returns the name of a temporary file which can be used by PDFLaTeX to include the image in the resulting PDF
• dbfile_string("name-of-file-in-database")
  This function can be used to include the content of the uploaded file in the resulting template. Note that this isn't generally useful for images, but may be useful for e.g. inclusion of standard text
• dbfile_base64("name-of-file-in-database")
  This function returns the content of the uploaded file as a base64 encoded string. This can be used to generate monolithic HTML files which include their images inline using "data" URLs. E.g.: <img src="data:image/png;base64,<?lsmb dbfile_base64('name-of-file-in-database') ?>">

Please see the "letterhead" templates (found in "templates/demo/" or "templates/xedemo/") for usage examples.

Downloadable reports now stored in the database for customization

This release adds the templates for the P&L, Balance sheet, Trial balance and generic listing reports to the list of customizable-per-company reports. In older releases, these reports had hard-coded layouts and were generally applicable to all companies on a single server.With the changes in this release, the templates are now available under the System > HTML Templates and System > LaTeX Templates menus.

Note for upgrades: When upgrading to 1.8 from earlier versions, these templates will need to be loaded into the database in setup.pl (mass-loading all available templates - overwriting what customizations might be in the database) or through the menus mentioned above, loading only the missing templates, leaving other customized templates in place.

New e-mail configuration in 'ledgersmb.conf'

To start: this release deprecates the "sendmail" configuration. Although sendmail will still be invoked when no "smtphost" key is configured, the invocation is no longer configurable. The sendmail binary will be searched for in the PATH, as well as on standard unix locations (/usr/sbin and /usr/lib).

This release adds the following new e-mail configuration keys, all to be used in the '[mail]' section of ledgersmb.conf:

• smtpauthmech
  A space separated list of SASL mechanisms to be used for authentication of the smtp connection with the SMTP server.  Available mechanisms depend on your installed environment, but the following mechanisms should be available in all of them: PLAIN LOGIN CRAM_MD5 DIGEST_MD5
  Note that PLAIN or LOGIN send passwords in plain text over the wire to the SMTP server; only use these methods in combination with TLS encryption.
• smtptls
  Can be one of 'no' (default), 'yes' or 'raw'. 'yes' indicates to use STARTTLS over a regular SMTP connection; 'raw' indicates an SMTP connection should be established over a TLS connection (a.k.a. smtps).
• smtpsender_hostname (optional)
  When set, used to identify the host when connecting to an SMTP server. When not set, the host is queried for its host name.

Import of OFX bank statement files for reconciliation

To help reconciliation, LedgerSMB has long supported upload of CSV files with bank transactions and since more recently also supports ISO-20022 CAMT-053 files. CSV files need customization of the installation and are therefore relatively hard to use for non-technical users. The CAMT-053 format doesn't require customization and is therefore much easier to use. However, the format isn't as widely available as hoped when implemented. The OFX format also doesn't require customization, expanding the options for non-technical users to automate their reconcilation process.

Notable changes

Reconciliation takes payments as first-order transactions

The logic of what constitutes a line on the reconciliation report have changed: this release uses the basic approach that every payment is a single line on the reconciliation report; any lines on the reconciled account that cannot be linked to a payment will be aggregated by their "Source" value. When no "Source" is supplied, the lines are entered into the report individually. This approach differs from prior releases where payments were no criterion in the creation of reconciliation lines. Approved reports are not affected by this change in paradigm.

Note for upgrades: Due to the conceptual difference between the old and new approaches, it's impossible to update and approve reconciliations started prior to 1.8 with version 1.8; therefore the upgrade insists any non-approved (saved, submitted) reports be deleted or approved before upgrade.

Fixes for migration of LedgerSMB 1.2 and 1.3 databases

The migration process of LedgerSMB 1.2 and 1.3 databases to 1.8 has more steps than that for 1.4+. The initial steps had a number of issues that were found during multiple migrations. The fixes and changes in code structure mean that more companies are likely to be able to migrate their data to LedgerSMB 1.8 with the built-in procedure (thus without specialized consulting services).

Other user-visible changes

• Document template (invoices/orders/etc..) management UI overhaul
  The new UI is located under the menu "System > Templates". The menu-items listing each template separately, has been removed.
• Default "today" value now derived from client instead of server
  Due to the fact that the value was derived from the server, the default date ("today") could be off by a day when the client and server resided in different timezones. The new value is determined on the client, ensuring alignment between the user's location and the calculation of the date.
• Manually entered tax lines from invoices selectively saved
  Before this release, all manually entered tax lines would be saved; even if the tax amount as well as the base amount (the amount the tax relates to) are zero. This release doesn't save lines anymore where both values are zero. Old data where both values are zero remains untouched.
• Single-entry time cards have been fixed
  The (broken-since-1.4) single-entry time cards have been fixed.

 

Upgrade notes

Draft reconciliations need to be posted or removed prior to upgrade

Due to a change in how reconciliations are recorded internally, the upgrade can't proceed when there are draft reconciliations in the database.

Report templates for PNL, Balance Sheet and Generic Report must be uploaded after upgrade

As-of 1.8, LedgerSMB expects these templates to be stored in the database. The upgrade procedure does not perform this upload. To upload these templates, traverse the menu "System > Templates", select "Income statement", "Balance sheet" and "Reports", in combination with formats "csv", "html" and "tex" respectively. There, the templates can be set by copy/pasting the content from the respective files in the templates directory: PNL.*, balance_sheet.* and display_report.*

Alternatively, when reading this document as part of your upgrade from 1.7 to 1.9(or later), use the command-line tool "ledgersmb-admin" to upload the desired templates.

Authentication problems immediately after logging in

1.8 uses encrypted cookies. The secret used to encrypt the cookie is automatically generated when the application is loaded. Starman (and other forking PSGI servers) loads the application in each process separately. This leads to each process generating its own cookie secret; this means that cookies from one request handling process will be rejected by other request handlers, leading to the behaviour observed. Please include the --preload-app option to the Starman command-line to prevent this problem.

The example systemd and SysV init scripts in the 1.8 release tarball have this parameter enabled out of the box. Please note that this parameter wasn't present in the example configuration scripts of 1.7 and earlier. When upgrading, please check your specific version.

[Upgrade] ERROR: duplicate key value violates unique constraint "ar_invnumber_key"

After upgrading, users can run into this error, which means that the "Sales Invoice/AR Transaction Number" in the "System > Defaults" page under the "Next in Sequence" section needs to be manually incremented by 1. Admins may want to verify ahead of moving the upgrade to production that the other sequences do not contain the last-used number, but indeed list the next number to be used.