18.4 System menu settings

This is a Yes/No value which affects the actions which can be performed on posted financial transactions.

• •

  No means transactions can be altered or deleted, even after posting them. Note that if a transaction has been posted before the latest closing date, it can never be altered, not even when this value is in effect.

• •

  Yes means transactions can’t be altered after posting. This setting is highly preferred and considered the only correct approach to accounting as it assures visible audit trails and thereby supports fraud detection.

@@@ This item isn’t a system setting; shouldn’t it move to “Transaction approval”?? That way system settings (config) and processes are separated.

@@@ My preference is to remove the setting entirely and rely on year-end workflow. We might add an account checkpoint interface as well at some point –Chris T

It’s advisable to regularly close the books after review. This prevents user error changing reviewed numbers: after closing the books, it’s no longer possible to post in the closed period.

There are also performance benefits to closing the books, because LedgerSMB uses the fact that the figures are known-stable as a performance optimization when calculating account balances.

This is a Yes/No value which - when Yes - causes the system to install triggers to register user actions (creation/adjustments/reversals/etc…) executed on financial transactions.

@@@ Once activated, where can we see it the audit trail??

@@@ This setting should go. In 1.3 the audit trails are always enforced via triggers so this setting does nothing. –CT

This is used to store an arbitrary identification number for the business. It could be used to store a business license number or anything similar.

The unit of measurement for weights. @@@ why don’t we have a unit of measurement for distance as well??? And maybe a unit of measurement for content?

Separation of duties is a method to help reduce fraud where one employee can’t modify the accounting ledger without another employee’s approval.

Select ”Yes” if you want to activate separation of duties or ”No” if you don’t want to activate it.

In order for separation of duties to be enforced, user roles have to be set differently for each user. This is done by removing the draft_post role from the users that cannot post and making sure that the users that can post have the role enabled. See Section 24.3 on page 24.3 for more details about changing and setting User Roles.

This setting will be used to preselect an account in the listings of the three categories listed below:

• •

  Inventory

• •

  Income

• •

  Expense

When working with foreign currencies, the system needs two special purpose accounts. One to post the gains onto which are caused by foreign currencies increasing in value; the other to post the losses onto which are caused by foreign currencies decreasing in value.

This setting indicates which country needs to be pre-selected in country selection lists.

The language to be used when no other language has been selected. Several parts of the application require language selection, such as customer, vendor and employee entry screens.

This setting indicates which set of templates - stored in the templates/ directory - should be used. In a standard installation, the drop down lists two items:

demo

which contains templates based on LaTeX, which is more commonly installed but has issues dealing with accented characters

Enter a list of all currencies you want to use in your company, identified by their 3-letter codes separated by a colon; i.e. “USD:EUR:CHF”. To ensure correct operation of the application, at least one currency (the company default currency) must be listed. In case of multiple currencies the first is used as the company default currency.

The fields “Company Name”, “Company Address”, “Company Phone” and “Company Fax” will be used on printed/e-mailed invoices.

This is an integer value field measuring the validity period in days for passwords set through the user’s Preferences screen. If this field is empty, passwords set through that method won’t expire.

The user has to log into LedgerSMB after this field is changed and prior to the expiration of the previous setting in order for the new duration to take effect.

A user will receive password expiration reminders upon logging starting a week before password expiry. When not acted upon, starting two days before expiry an hourly popup will appear requesting the user to change the password.

The application behaves this way because users with expired passwords won’t be able to log in: their password will need to be reset by a user admin.

Note that passwords set by admins for other users expire within 24 hours after setting them. This value is hard coded and can’t be overruled. This is a security measure taken to make sure as few unused accounts as possible exist: Existence of such accounts could open up security holes.

These addresses will be used to send e-mails from the system. Note that the “Default Email From” address should be configured in order to make sure e-mail doesn’t look like it’s coming from your webserver. The format to be used is ‘‘Name’’ <e-mail address> where the e-mail address should be inserted between the “$⟨$” and “$⟩$”.

Some elements in the screens may present a drop down. However, drop downs are relatively unwieldy to work with when used to present a large number of values to choose from.

This configuration option sets an upper limit on the number of records to be presented as drop down. When the number is exceeded, no drop down is used. Instead, a multi-step selection procedure will be used.

Many items in the system have sequence numbers: invoices, parts, etc. These can be just a number (i.e. 1 or 37) or they can also be both prefixed and suffixed. For example, INV0001 for invoices and EMP001 for employees or YOU-0001TOO, in which case the next item will be YOU-0002TOO.

You can only issue every number in the sequence once, but you can issue Y21-001 and Y22-001 by changing the sequence number format at the beginning of the year.

The numbers shown in the input boxes will be used to generate the next number in the numbering sequence.

GL Reference number

The default reference number for the next GL transaction.

Sales invoice/ AR Transaction number

This number is used to generate an invoice number when none is being filled out by the user.

Sales order number

Same as Sales invoice number, except that it’s used for sales orders @@@ layout issue: the label is too big to fit on the page

Vendor invoice/ AP Transaction number

Same as Sales invoice, except that the number is used for accounts payable transactions. @@@ layout issue: the label is too big to fit on the page

Sales quotation number

Same as sales order number, except that it’s used for quotations.

RFQ number

Request for quotation number is like the sales quotation number, except that it is used to track which vendors have been asked for quotes.

Part number

All parts, services and assemblies are identified by a unique number. When an item is created and no number is entered by the user, a number is generated from this sequence.

Job/project number

Used when creating new projects.

Employee number

Same as the sales invoice number, used by new employee entry.

Customer number

@@@ is this the control code number? or is this meta_number?? – Meta-number (CT)

Vendor number

@@@ same question as customer number

The prefix to use when printing checks. There’s no check sequence number. That sequence number is requested from the check printing interface, because checks can be created outside the application as well, meaning the numbers can get out of sync.

To change a LaTeX template navigate to System $\to$ Templates. Select, for example, Template ”Invoice” and Format ”tex”, you should see the view shown in Figure 18.6 on page 18.6

To add a file to the latex template, first upload the image file to the database. This can be accomplished by navigating to System $\to$ Files.

To include this graphic file in your LaTeX document, it needs to be retrieved from the database and temporarily stored in a location accessible to the PDF generator. Once the file is in the database, then the function dbfile_path handles that.

For example, If the graphic file is named ”FL_Logo_icon_250x250.png”, then add something like the following to the LaTeX template using the Edit button.

\parbox[b]{.1\textwidth}{%
    \includegraphics[scale=0.7]{%
        <?lsmb dbfile_path("FL_Logo_icon_250x250.png")?>}
}

After editing the template must be uploaded to the database using the Upload button.

Editing an HTML template is exactly the same as editing a LaTeX document except that the language is HTML instead of LaTeX.

Editing an CSV template is exactly the same as editing a LaTeX document except that the language is basically all template vars instead of LaTeX.

Templating directives in are expressed with the base form of <?lsmb foo ?>. That, and basic variable substitution, is about the only part of templating that has remained unchanged. Starting with LedgerSMB1.3, the primary rendering engine is Template Toolkit, with START_TAG changed to “<?lsmb” and END_TAG changed to “?>”.

For simple output, the name of the variable is placed on its own, as in <?lsmb foo ?>. Hash elements are accessed using the form <?lsmb hash.key ?>. Arrays are treated as a form of hash where the key is the index of the element, indexed from zero. In more complex cases, such as where the desired hash key is the value of another variable, values can be extracted by prefixing the name of the other variable with $. This results in the form <?lsmb row.$column ?>.

Through Template Toolkit, LedgerSMB::Template has the concept of private variables. If any component of the variable name starts with an underscore, it is private and will not be output to the rendered document.

Something to watch for when dealing with variable substitution for hashes is that in some cases, the key name conflicts with one of Template Toolkit’s VMethods for the type. When that occurs and the value is not defined, the VMethod is executed instead of retrieving the value. An example of where this could happen is when retreiving the value of form.sort. As it is often undefined and included in “hidden” HTML elements, it can cause application errors when a templater attempts to retrieve it using form.sort instead of form.item(’sort’).

In addition to the regular Template Toolkit functions, LedgerSMB has the additional functions text and gettext. Both of these functions are interfaces to the underlying gettext infrastructure and both can handle simple gettext substitutions. The difference between these functions is that text makes use of the locale of the current user, while gettext must be passed a string that identifies one of the gettext translations.

These gettext lookups can take placeholders in the same syntax that the underlying Perl does, “[_n]”. The output of the i18n functions is not escaped and the input values are not unescaped.

<?lsmb gettext(’fr_CA’, ’Item #[_1]’, value) ?>

The only formatting function that is added is escape. The escape function escapes a value using the rules for the template format.

The base IF, ELSIF, ELSE FOREACH

Two template-side tools that can help with debugging are the interface to Data::Dumper and setting a debug message format.

Variable Dumping

The Data::Dumper interface is loaded using <?lsmb USE dumper() ?> and used with either <?lsmb dumper.dump(var) ?> or <?lsmb dumper.dump_html(var) ?>. Both dumper.dump and dumper.dump_html perform the same basic dumping, however dump_html also escapes the values and applies basic formatting. See Template::Plugin::Dumper for details.

Logging

Template Toolkit has a DEBUG directive that can cause line-based logging messages to appear in the rendered output when the debug flag to LedgerSMB::Template is true. A sample tag to start a debugging region with LaTeX templates is <?lsmb DEBUG format ’% $file:$line $text’ ?>. The debugging messages will start with the line that has the directive and a debugging region can be optionally terminated with <?lsmb DEBUG format ” ?>, which tells TT to use an empty message.

A new templating API was added in LedgerSMB 1.3. This API is accessed through LedgerSMB::Template, and has several support modules. Typical usage of this API is fairly simple in that most places that use it instantiate a LedgerSMB::Template object in auto-output mode then use the resulting object’s render method. The constructor options are detailed in the POD for LedgerSMB::Template with the most interesting one for designing and testing user interface templates probably being “debug”, which enables the display of debugging messages. The render method handles escaping the passed in template data for the selected output format and the actual rendering with the appropriate support module.

Options

@@@TODO

Input

@@@TODO

Output

@@@TODO

LedgerSMB::Template::LaTeX

This module uses Template::Latex to generate DVI, PDF, or Postscript output. It looks for template files that end in “.tex” and take marked-up LaTeX. Rendering of templates by these modules happens in two phases: the TT phase and the LaTeXphase. All templates that are directly called by LedgerSMB::Template that use these modules must be enclosed by the tag pair <?lsmb FILTER latex ?> and <?lsmb END ?> for the second rendering phase to occur. The final output file format is determined by the format_option filetype.

LedgerSMB::Template::HTML

This is the most frequently used LedgerSMB::Template module as the migration of the user interface to templates has started. It looks for template files that end in “.html”.

LedgerSMB::Template::CSV

A new form of output with LedgerSMB1.3, this module is used by some reports to give output in a standard form. It looks for template files that end in “.csv”.

LedgerSMB::Template::ODS, LedgerSMB::Template::XLS This pair of module outputs spreadsheets. Their input is specially formatted XML files that are processed by TT before the final conversion from XML to their respective formats. Details about the XML format are available in the documentation for Excel::Template.

The templates used by these modules have the extensions “.odst” and “.xlst”.

LedgerSMB::Template::TXT

A format infrequently used by LedgerSMB, this is used for Point Of Sale invoices. It looks for templates that end in “.txt”.

LedgerSMB::Template::TTI18N

This module defines some internationalization functions that can be called in templates that use Template Toolkit.

LedgerSMB::Mailer

This module provides the functions used by LedgerSMB::Template and the backup routines in the administration module to email files and documents.

LedgerSMB1.3 to LedgerSMB1.2

• •

  A new templating API was added to replace Form::parse_template

• •

  The main rendering engine was changed to Template Toolkit

• •

  Migration of the user interface to using LedgerSMB::Template was started

• •

  DVI, Excel, OpenDocument Spreadsheet, and CSV output support was added

• •

  The LedgerSMB::Mailer API was changed and documented

LedgerSMB1.2 to LedgerSMB1.1

• •

  Tags were changed from the form <% foo %>to <?lsmb foo ?>

• •

  The ability to compare two variables in templates was removed

• •

  LedgerSMB::Mailer was rewritten to use MIME::Lite while retaining the old API

• •

  SMTP support was added to LedgerSMB::Mailer