diff options
Diffstat (limited to 'doc/manual/LedgerSMB-manual.tex')
| -rw-r--r-- | doc/manual/LedgerSMB-manual.tex | 2431 |
1 files changed, 2431 insertions, 0 deletions
diff --git a/doc/manual/LedgerSMB-manual.tex b/doc/manual/LedgerSMB-manual.tex new file mode 100644 index 00000000..dabe5a98 --- /dev/null +++ b/doc/manual/LedgerSMB-manual.tex @@ -0,0 +1,2431 @@ +\documentclass{article} +\usepackage{metatron} +\renewcommand{\abstractname}{Executive Summary} +\newcommand{\mycustomer}[1][]{#1\space} +\newcommand{\myproject}[1][]{#1\space} +\title{Ledger-SMB Manual} +\author{Chris Travers (\metamail{chris})} +\date{\today} +\begin{document} +\maketitle + + Copyright \copyright 2006 Metatron Technology Consulting. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.2 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU + Free Documentation License" (Appendix \ref{fdl}). + + +\tableofcontents + +\listoffigures + +\clearpage + +\part{Ledger-SMB and Business Processes} +\section{Introduction to Ledger-SMB} +\subsection{Why Ledger-SMB} +\subsubsection{Advantages of Ledger-SMB} +\begin{itemize} +\item Flexibility and Central Management +\item Accessibility over the Internet (for some users) +\item Data is in a relatively open format +\item Integration with other tools +\item One of the best accounting options for Linux users. +\item Open Source +\item A flexible, open framework that can be extended or modified to fit your +business. +\item Security-conscious development community. +\end{itemize} +\subsubsection{Key Features} +\begin{itemize} +\item Accounts Receivable + \begin{itemize} + \item Track sales by customer + \item Issue Invoices, Statements, Receipts, and more + \item Job costing and time entry for customer projects. + \item Manage sales orders and quotations + \item Ship items from sales orders + \end{itemize} +\item Accounts Payable + \begin{itemize} + \item Track purchases and debts by vendor. + \item Issue RFQ's Purchase Orders, etc. + \item Track items received from purchase orders. + \end{itemize} +\item Budgeting + \begin{itemize} + \item Track expenditures and income across multiple departments. + \item Track all transactions across departments. + \end{itemize} +\item Check Printing + \begin{itemize} + \item Can customize template for any check form + \end{itemize} +\item General Ledger +\item Inventory Management + \begin{itemize} + \item Track sales and orders of parts + \item Track cost of goods sold using First In/First Out method + \item List all parts below reorder point. + \item Track ordering requirements. + \item Track, ship, receive, and transfer parts to and from multiple + warehouses. + \end{itemize} +\item Localization + \begin{itemize} + \item Provide Localized Translations for Part Descriptions + \item Provide Localized Templates for Invoices, Orders, Checks, and more. + \item Select language per customer, invoice, order, etc. + \end{itemize} +\item Manufacturing + \begin{itemize} + \item Track cost of goods sold for manufactured goods (assemblies) + \item Create assemblies and stock assemblies, tracking materials on hand. + \end{itemize} +\item Multi-company/Multiuser + \begin{itemize} + \item One isolated database per company + \item Users can have localized systems independent of company data set. + \end{itemize} +\item Point of Sale + \begin{itemize} + \item Run multiple cash registers against main Ledger-SMB installation. + \item Suitable for retail stores and more. + \item Supports some POS hardware out of the box. + \item Third party add-ons available for more functionality. + \end{itemize} +\item Price Matrix + \begin{itemize} + \item Track different prices for vendors and customers across the board. + \item Provide discounts to groups of customers per item or across the board. + \item Store vendors' prices independent of the other last cost in the + parts record. + \end{itemize} +\item Reporting + \begin{itemize} + \item All basic financial statements supported. + \item Customer history, sales data, and additional information can be easily + displayed. + \item Open framework allows for ODBC connections to be used to generate + reports using third party reporting tools. + \end{itemize} +\item Tax + \begin{itemize} + \item Supports Retail Sales Tax and Value Added Tax type systems + \item Flexible framework allows one to customize reports to change the tax + reporting framework to meet any local requirement. + \end{itemize} +\end{itemize} + +\subsection{Limitations of Ledger-SMB} +\begin{itemize} +\item No payroll module (Payroll must be done manually) +\item Some integration limitations +\item Further development/maintenance requires a knowledge of a relatively + broad range of technologies. +\end{itemize} + +\subsection{System Requirements of Ledger-SMB} +\begin{itemize} +\item PostgreSQL +\item A CGI-enabled Web Server (for example, Apache) +\item Perl with the DBI and DBD::Pg modules +\item An operating system which supports the above software (usually Linux, + though Windows, MacOS X, etc. do work). +\item \LaTeX\ (optional) is required to create PDF or Postscript invoices. +\end{itemize} + +\section{User Account and Database Administration Basics} + +These functions are accessed by going to the admin.pl script in the installed +directory of Ledger-SMB. + +\subsection{Companies and Datasets} + +Ledger-SMB stores its information in locale-specific data sets. When a dataset +is created, it sets various defaults such as currency, a basic chart of accounts +setup, and so forth. Note that the default setup is for Canada, where the +author of the software resides. + +Datasets are generally tracked as PostgreSQL databases. The application is +designed with the idea that each dataset will represent exactly one company. If +a customer is working with multiple companies, he/she must create a dataset to +for each. + +\subsection{How to Create a User} + +Users are created by going to the admin.pl page and clicking on "Add User." One +then fills out the form and when it is saved, the user is created. + +\subsection{Permissions} + +The permissions system is not rigorously enforced within Ledger-SMB, in the +sense that the permissions API is generally not used in the application itself. +Instead permissions are used to enable/disable menu options. Setting an +enforcement of such permissions would require some custom programming at the +present time. Most organizations, however, find that the current system is +adequate. + +The checkboxes which are marked enable menu entries. Those that are unchecked +disable those entries on the menu. + +\subsection{User Account Types} + +\begin{itemize} +\item User is a general user of the system +\item Managers often are able to see a larger amount of data +\item Administrators have full access to the system +\end{itemize} + +\subsection{Other Features} +\begin{itemize} +\item Lock System allows one to lock users out of the system while maintenance +is performed. This is only necessary during upgrades or maintenance which +results in the RDBMS being offline. +\item Change Admin Password. +\item Logout terminates the admin session. +\end{itemize} + +\section{Chart of Accounts} +The Chart of Accounts provides a basic overview of the logical structure of the +accounting program. One can customize this chart to allow for tracking of +different sorts of information. + +\subsection{Introduction to Double Entry Bookkeeping} + +Ledger-SMB is a double entry system, meaning that every transaction consists of +an equal sum of credits and debits (see below). A transaction is said to be +balanced when the debits and credits are equal. This is an oversimplification +and doesn't cover more complex processes involving closing books properly. In +general customers should be referred to their accountants for information beyond +the capabilities of the software. This module is just designed to provide +enough familiarity with the concepts to be able to have an intelligent +conversation with a bookkeeper or accountant who has specific requirements in +this regard. + +\subsubsection{Account Types} + +\begin{itemize} +\item Assets represent tangible or intangible property or money +retained by the company. This includes money owed to the company. +\item Liabilities are money that the company owes others. +\item Equity is the valuation of the company as a whole. Includes investment +capital, and money paid out to owners either as dividends or as withdrawals (for +sole proprietorships). Normally one will have at least three equity accounts: +One for tracking investment in the business, one for tracking withdrawals or +dividends, and one for tracking retained earnings. +\item Income accounts track the category of money as it is earned by the +business. +\item Expense accounts track the category of money flowing out as expenses are +accrued. +\end{itemize} + +\subsubsection{Debits and Credits} + +Debits and credits are the basic unit of double-entry bookkeeping. When money +is removed from the business by the owners (as an equity payment) that is a +debit, while when money is invested in the business, that is a credit. Every +other transaction is set to balance these concepts. Therefore asset accounts +normally have a debit balance because this allows for the equity account to be +debited, while expense accounts normally have a credit balance. + +If the total debits is not equal to the total credits in the chart of accounts, +something is very wrong, and the customer should get technical support +immediately. + +\subsubsection{A few Examples} + +One might have a business that rents an office space. When +rent is due, the accounts payable account would be credited, while the rent +expense account would be debited. When this is paid, the accounts payable +account would be debited while the asset account would be credited. This may +seem backwards, but the result is to reduce by the amount owed for rent the +amount that the owners can withdraw from the business as a debit. Let's say the +office rent is \$300. + +\begin{itemize} +\item Rent expense account is debited \$300 +\item Accounts Payable is credited \$300 +\item When this is paid, the checking account is credited \$300 +\item And the Accounts Payable is debited \$300 +\end{itemize} + +Let us say one performs a small consulting project for \$600. At the completion +of this project, the following transaction would be made: + +\begin{itemize} +\item Accounts Receivable is debited \$600 +\item Income (Consulting) is credited \$600. +\end{itemize} + +Then the customer pays the \$600, the following transaction is entered. +\begin{itemize} +\item Accounts Receivable is credited \$600 +\item Payments Received is debited \$600. +\end{itemize} + +\subsection{General Guidelines on Numbering Accounts} +In general, most drop-down boxes in Ledger-SMB order the accounts by account +number. Therefore by setting appropriate account numbers, one can affect the +default values. + +A second consideration is to try to keep things under each heading appropriate +tot hat heading. Thus setting an account number for a bank loan account in the +assets category is not generally advisable. + +\subsection{Adding/Modifying Accounts} + +These features are listed under System-\textgreater Chart of Accounts. +One can list the accounts and click on the account number to modify them or +click on the "add account" option to create new accounts. + +\begin{itemize} +\item Headings are just broad categories and do not store values themselves, +while accounts are used to store the transactional information. +\item One cannot have an account that is both a summary account (like AR) but +also has another function. +\item GIFI is mostly of interest to Canadian customers but it can be used to +create reports of account hierarchies. +\end{itemize} + +\subsection{Listing Account Balances and Transactions} +One can list the account balances via the Reports-\textgreater Chart of Accounts report. +Clicking on the account number will provide a ledger for that account. + +\section{Administration} + +This section will cover other (non-Chart of Accounts) aspects to the setup of +the Ledger-SMB accounting package. These are generally accessed in the System +submenu. + +\subsection{Taxes, Defaults, and Preferences} +\subsubsection{Adding A Sales Tax Account} + +Sales Tax is collected on behalf of a state of national government by the +individual store. Thus a sales tax account is a liability-- it represents money +*owed* by the business to the government. + +To add a sales tax account, one would create an account in the COA as a +liability account, check all of the "tax" checkboxes, and answer the following +question as "yes:" + +"Include this account on the customer/vendor forms to flag customer/vendor as +taxable?" + +Once this account is created, one can set the tax amount. + +\subsubsection{Setting a Sales Tax Amount} +Go to System-\textgreater Defaults and the tax account will be listed near the bottom of the +page. The rate can be set there. + +\subsubsection{Default Account Setup} +These accounts are the default accounts for part creation and foreign exchange +tracking. + +\subsubsection{Currency Setup} +The US accounts list this as USD:CAD:EUR. One can add other currencies in here, +such as IDR (Indonesian Rupiah), etc. Currencies are separated by colons. + +\subsubsection{Sequence Settings} +These sequences are used to generate user identifiers for quotations, invoices, +and the like. If an identifier is not added, the next number will be used. + +A common application is to set invoices, etc. to start at 1000 in order to hide +the number of issued invoices from a customer. + +\subsection{Audit Control} + +Auditibility is a core concern of the architects of any accounting system. Such +ensures that any modification to the accounting information leaves a trail which +can be followed to determine the nature of the change. Audits can help ensure +that the data in the accounting system is meaningful and accurate, and that no +foul play (such as embezzlement) is occurring. + +\subsubsection{Explaining transaction reversal} +In paper accounting systems, it was necessary to have a means to authoritatively +track corrections of mistakes. The means by which this was done was known as +"transaction reversal." + +When a mistake would be made, one would then reverse the transaction and then +enter it in correctly. For example, let us say that an office was renting space +for \$300 per month. Let us say that they inadvertently entered it in as a +\$200 expense. + +The original transaction would be: + +\begin{tabular}{l|r|r} +Account & Debit & Credit \\ +\hline +5760 Rent & \$200 & \\ +2100 Accounts Payable & & \$200\\ +\end{tabular} + +The reversal would be: + +\begin{tabular}{l|r|r} +Account & Debit & Credit \\ +\hline +5760 Rent & & \$200\\ +2100 Accounts Payable &\$200 & \\ +\end{tabular} + +This would be followed by re-entering the rent data with the correct numbers. +This was meant to ensure that one did not erase data from the accounting books +(and as such that erasing data would be a sign of foul play). + +Ledger-SMB has a capability to require such reversals if the business deems this +to be necessary. When this option is enabled, existing transactions cannot be +modified and one will need to post reversing transactions to void existing +transactions before posting corrected ones. + +Most accountants prefer this means to other audit trails because it is well +proven and understood by them. + +\subsubsection{Close books option} +The option to close books requires transaction reversal for any transaction up +to a certain date. + +\subsubsection{Audit Trails} +This option stores additional information in the database to help auditors trace +individual transactions. The information stored, however, is limited and it is +intended to be supplemental to other auditing facilities. + +The information added includes which table stored the record, which employee +entered the information, which form was used, and what the action was. No +direct financial information is included. + +\subsection{Departments} +Departments are logical divisions of a business. They allow for budgets to be +prepared for the individual department as well as the business as a whole. This +allows larger businesses to use Ledger-SMB to meet their needs. + +\subsubsection{Cost v Profit Centers.} + +In general business units are divided into cost and profit centers. Cost +centers are generally regarded as business units where the business expects to +lose money and profit centers are where they expect to gain money. For example, +the legal department in most companies is a cost center. + +One of the serious misunderstandings people run up against is that Ledger-SMB +tends to more narrowly define cost and profit centers than most businesses do. +In Ledger-SMB a cost center is any department of the business that does not +issue AR transactions. Although many businesses may have cost centers (like +technical support) where customer fees may subsidize the cost of providing the +service, in Ledger-SMB, these are profit centers. + +Ledger-SMB will not allow cost centers to be associated with AR transactions. +So if you want this functionality, you must create the department as a profit +center. + +\subsection{Warehouses} + +Ledger-SMB has the ability to track inventory by warehouse. Inventory items can +be moved between warehouses, and shipped from any warehouse where the item is in +stock. We will explore this concept more later. + +\subsection{Languages} +Languages allow for goods and services to be translated so that one can +maintain offices in different countries and allow for different goods and +service descriptions to be translated to different languages for localization +purposes. + +\subsection{Types of Businesses} +One can create types of businesses and then give them discounts across the +board. For example, one might give a firm that uses one's services as a +subcontractor a 10\% discount or more. + +\subsection{Misc.} +\subsubsection{GIFI} + +GIFI is a requirement for Canadian customers. This feature allows one to link +accounts with Canadian tax codes to simplify the reporting process. + +It also has another use in that non-Canadians can use this functionality to +create customized reports by categorizing accounts using this field. This +allows for a sort of shallow "account hierarchy" like some users are used to +with other products. + +\subsubsection{SIC} + +Standard Industrial Classification is a way of tracking the type of business +that a vendor or customer is in. For example, an accountant would have an SIC +of 8721 while a graphic design firm would have an SIC of 7336. The +classification is hierarchical so one could use this field for custom reporting +and marketing purposes. + +\subsubsection{Overview of Template Editing} + +The templates for invoices, orders, and the like can be edited from within +Ledger-SMB. The submenus within the System submenu such as HTML Templates, +Text Templates and LaTeX templates provide access to this functionality. + +\subsubsection{Year-end} + +Although the Year-end functionality in Ledger-SMB is very useful, it does not +entirely make the process simple and painless. One must still manually enter +adjustments prior to closing the books. The extent to which these adjustments +are necessary for any given business is a matter best discussed with an +accountant. + +The standard way books are normally closed at the end of the year is by moving +all adjusted\footnote{Adjustments would be entered via the General Ledger. The +exact process is beyond the scope of this class, however.} income and expenses +to an equity account usually called "Retained +Earnings." Assets and liabilities are not moved. Equity drawing/dividend +accounts are also moved, but the investment accounts are not. The reasoning +behind this process is that one wants a permanent record of the amount invested +in a business, but any dividends ought not to count against their recipients +when new investors are brought on board. + +Ledger-SMB automatically moves all income and expense into the specified +year-end/retained earnings account. It does not move the drawing account, and +this must be done manually, nor does it automate the process of making +adjustments. + +Contrary to its name, this function can close the books at any time, though this +would likely be of limited use. + +\subsection{Options in the ledger-smb.conf} + +For those who are unfamiliar with Perl as a programming language, the +ledger-smb.conf configures the software by assigning site-wide variables. Most +of these should be left alone unless one knows what one is doing. However, on +some systems some options might need to be changed, so all options are presented +here for reference: + +\begin{itemize} +\item \$userspath is the directory where Ledger-SMB will store the user +accounts. The web server process must be able to read from and write to this +directory. +\item \$templates is the directory where the templates are stored. +\item \$memberfile is the master list of user configuration information +\item \$sendmail is the command to use to send a message. It must read the +email from standard input. +\item \$language allows one to set the language for the login screen and admin +page. +\item \$latex tells Ledger-SMB whether LaTeX is installed. LaTeX is required +for generating Postscript and PDF invoices and the like. +\item Various environmental variables (\$ENV...) can be set here too. One can +add paths for searching for LaTeX, etc. +\item \%printer can be used to set a hash table of printers for the software. +The primary example is\\ +\%printer = ( 'Default' =\textgreater 'lpr', 'Color' =\textgreater 'lpr -PEpson' ); \\ +However, this can use any program that can accept print documents (in +Postscript) from standard input, so there are many more possibilities. +\end{itemize} + +I have omitted the variables used to configure Oracle as I do not believe it is +still supported (it could be with a small amount of work though). + +\section{Goods and Services} + +The Goods and Services module will focus on the definition of goods and services +and the related accounting concepts. + +\subsection{Basic Terms} +\begin{description} +\item[COGS] is Cost of Goods Sold. When an item is sold, then the expense of +its purchase is accrued as attached to the income of the sale. It is tracked as +COGS. +\item[List Price] is the recommended retail price. +\item[Markup] is the percentage increase that is applied to the last cost to get the sell price. +\item[ROP] Re-order point. Items with fewer in stock than this will show up on +short reports. +\item[Sell Price] is the price at which the item is sold. +\end{description} + +\subsection{The Price Matrix} + +It is possible to set different prices for different groups of customers, or for +different customers individually. Similarly, one can track different prices +from different vendors along with the required lead time for an order. + +\subsection{Pricegroups} + +Pricegroups are used to help determine the discount a given customer may have. + +\subsection{Groups} + +Groups represent a way of categorizing POS items for a touchscreen environment. +It is not fully functional yet, but is sufficient that with some stylesheet +changes, it could be made to work. + +\subsection{Labor/Overhead} + +Labor/overhead is usually used for tracking manufacturing expenses. It is not +directly billed to a customer. It is associated with an expense/Cost of Goods +Sold (COGS) account + +\subsection{Services} + +Services include any labor that is billed directly to the customer. It is +associated with an expense/COGS account and an income account. Services can be +associated with sales tax. + +\subsubsection{Shipping and Handling as a Service} + +One approach to dealing with shipping and handling is to add it as a service. +Usually I place the unit as a dollar (USD) and then bill it as \$1 per unit. +This allows me to add the exact amount of shipping and handling as necessary. + +\subsection{Parts} + +A part is any single item you might purchase and either might resell or use in +manufacturing an assembly. It is linked to an expense/COGS +account, an income account, and an inventory account. Parts can be associated +with sales tax. + +\subsection{Assemblies and Manufacturing} + +Manufacturers order parts but they sell the products of their efforts. +Ledger-SMB supports manufacturing using the concept of assemblies. An assembly +is any product which is manufactured on site. It consists of a selection of +parts, services, and/or labor and overhead. Assemblies are treated as parts in +most other regards. + +However, one cannot order assemblies from vendors. One must instead order the +components and stock them once they are manufactured. + +%Excersize 1 + +\subsubsection{Stocking Assemblies} + +One stocks assemblies in the Stock Assembly entry on the Goods and Services +submenu. When an assembly is stocked the inventory is adjusted properly. + +The Check Inventory option will cause Ledger-SMB to refuse to stock an assembly +if the inventory required to produce the assembly would drop the part below the +reorder point. + +\subsection{Reporting} +\subsubsection{All Items and Parts Reports} + +The All Items provides a unified view of assemblies, parts, services, and labor +for the company, while the Parts report confines it to parts. + +Types of reports are: +\begin{description} +\item[Active] lists all items not marked as obsolete. +\item[On Hand] lists current inventory +\item[Short] Lists all items which are stocked below their ROP +\item[Obsolete] Lists all items which are marked as obsolete +\item[Orphaned] Lists all items which have never had a transaction associated +with them. +\end{description} + +One can also list these goods by invoice, order, or quotation. + +For best results, it is a good idea to enter some AR and AP data before running +these reports. + +\subsubsection{Requirements} + +This report is designed to assist managers determine the quantities of goods to +order and/or stock. It compares the quantity on hand with the activity in a +given time frame and provides a list of goods which need to be ordered and the +relevant quantity. + +\subsubsection{Services and Labor} +This is similar to the Parts and All Items menu but only supports active, +obsolete, and orphaned reports. + +\subsubsection{Assemblies} + +This is similar to the Parts and All Items reports but it also provides an +ability to list individual items in the assemblies as well. + +AP Invoices, Purchase Orders, and RFQ's are not available on this report. + +\subsubsection{Groups and Pricegroups} + +These reports provide a simple interface for locating groups and pricegroups. +The report types are similar to what they are for services. + +\subsection{Translations} +One can add translations so that they show up in the customer's native language +in the issued invoice. + +To issue translations, one must have languages defined. One can then add +translations to descriptions and part groups. + +\subsection{How Cost of Goods Sold is tracked} +Cost of Goods Sold is tracked on a First-In, First-out (FIFO) basis. When a +part is purchased, its cost is recorded in the database. The cost of the item +is then added to the inventory asset account. When the good is sold, the cost +of the item is moved to the cost of goods sold account. + +This means that one must actually provide invoices for all goods entered at +their actual cost. If one enters in \$0 for the cost, the cost of goods sold +will also be \$0 when the item is sold. We will cover this entire process in +more depth after we cover the AP and AR units below. + +\section{AP} +\subsection{Basic AP Concepts} +The Accounts Payable module tracks all financial commitments that the company +makes to other businesses. This includes rent, utilities, etc. as well as +orders of goods and services. + +\subsection{Vendors} +A vendor is any business that the company agrees to pay money to. + +One can enter vendor information under AP-\textgreater Vendors-\textgreater Add Vendor. The vendor list +can be searched under AP-\textgreater Vendors-\textgreater Reports-\textgreater Search. + +In older versions of Ledger-SMB, vendors would continue to populate the list of +active vendors forever and there was no way to delete them. Now one can enter +start and end-dates and this can be used to filter out vendors in searches or +drop-down boxes. + +A few fields that need explanation are: +\begin{description} +\item[BIC] Bank Identifier Code is often the same as the S.W.I.F.T. code. This +is a code for the bank a customer uses for automated money transfers. +\item[IBAN] International Bank Account Number is related to the BIC and is used +for cross-border automated money transfers. +\item[Terms] is the number of days one has to pay the invoice. +\item[Vendor Number] is automatically generated. +\end{description} + +\subsection{AP Transactions} +AP Transactions are generally used for items other than goods and services. +Utilities, rent, travel expenses, etc. could be entered in as an AP transaction. + +If the item is paid partially or in full when the transaction is entered, one +can add payments to the payment section. + +All other payments can and should be entered under cash payment (below). + +The PO Number and Order Number fields are generally used to track associations +with purchase orders sent to vendors, etc. These fields can be helpful for +adding misc. expenses to orders for reporting purposes. + +The department drop-down box appears when one has created one or more +departments. A transaction is not required to be associated with a department, +but one can use this feature for budget tracking. + +With AP Transactions, there is no option for internal notes. All notes will +appear on any printed version of the transaction. + +Note: Printing a transaction does not post it. No data is committed until the +invoice is posted. + +\subsection{AP Invoices} +AP Invoices are used to enter in the receipt of goods and services. Goods and +services are deemed entered into the inventory when they are invoiced. + +This screen is reasonably similar to the AP Transaction Screen, though the part +entry section is a bit different. + +The AP Invoice section has a capacity to separate internal notes from notes +printed on the invoice. Note, however, that since these are received invoices, +it is rare that one needs this ability. + +Note that Ledger-SMB can search for partial part numbers or descriptions. + +Also if you have a group you can use this to select the part. + +To remove a line item from an invoice or order, delete the partnumber and click +update. + +\subsubsection{Correcting an AP Invoice} +If an invoice is entered improperly, the methods used to correct it will vary +depending on whether transaction reversal is enforced or not. If transaction +reversal is not enforced, one can simply correct the invoice or transaction and +repost. + +If not, one needs to create a *duplicate* invoice with exactly opposite values +entered. If one part was listed as received, then one should enter a negative +one for the quantity. Then one can enter the invoice number as the same as the +old one (though I like to add an R to the end to show that it is a reversing +transaction). Once this is posted, one can enter the invoice correctly. + +\subsection{Cash payment And Check Printing} +In general, it is a bad idea to repost invoices/transactions just in order to +enter a payment. The Cash-\textgreater Payment window allows one to enter payments against +AP invoices or transactions. + +The printing capability can be used to print checks. The default template is +NEBS 9085, though you can use 9082 as well (as Quickbooks does). + +The source field is used to store an identifying number of the source document, +such as the check number. One must select the item to have it paid, and then +enter the amount. One can then print a check. + +\subsubsection{Rapid Payment Entry Screen} + +One can also use the rapid payment entry screen to print multiple checks. +However, this does not allow you to print the multiple checks to the screen as a +separate document is created for each check. In this event, one must print +directly to a printer as postscript. + +\subsection{Transaction/Invoice Reporting} +\subsubsection{Transactions Report} + +This report is designed to help you locate AP transactions based on various +criteria. One can search by vendor, invoice number, department, and the like. +One can even search by the shipping method. + +The summary button will show what was placed where, while the details button +will show all debits and credits associated with the transaction. + +To view the invoice, click on the invoice number. In the detail view, to view +the account transactions as a whole, click on the account number. + +Open invoices are ones not fully paid off, while paid closed invoices are those +that have been paid. + +\subsubsection{Outstanding Report} +The outstanding report is designed to help you locate AP transactions that are +not paid yet. The ID field is mostly useful for locating the specific database +record of a duplicate invoice number exists. + +\subsubsection{AP Aging Report} +This report can tell you how many invoices are past due and by how much. + +A summary report just shows vendors while a detail report shows individual +invoices. + +\subsubsection{Tax Paid and Non-taxable Report} +These reports are not generally used in the US because most of the time +wholesale goods are not taxable. However, for businesses with offices in other +countries including Canada, it is often important for them to be aware of this +functionality. In these countries, one generally pays sales tax even on +wholesale goods and then takes a tax credit for these when when paying the sales +tax to the country of province. Thus one needs to be able to track taxable and +non-taxable expenses, and how much was paid. For now, it is sufficient to know +that they are there. + +\subsection{Vendor Reporting} +\subsubsection{Vendor Search} +The Vendor Search screen can be used to locate vendors or AP transactions +associated with those vendors. + +The basic types of reports are: + +\begin{description} +\item[All] Lists all vendors +\item[Active] Lists those vendors currently active +\item[Inactive] Lists those vendors who are currently inactive. +time frame. +\item[Orphaned] Lists those vendors who do not have transactions associated with +them. These vendors can be deleted. +\end{description} + +One can include purchase orders, Requests for Quotations, AP invoices, and AP +transactions on this report as well if they occur between the from and to dates. + + +\subsubsection{Vendor History} +This report can be used to obtain information about the past goods and services +ordered or received from vendors. One can find quantities, partnumber, and +sell prices on this report. This facility can be used to search RFQ's, Purchase +Orders, and AP Invoices. + +\section{AR} +\subsection{Customers} +Customers are entered in using the AR-\textgreater Customers-\textgreater Add Customer menu. + +The salesperson is autopopulated with the current user who is logged in. +Otherwise, it looks fairly similar to the Vendor input screen. Customers, like +vendors can be assigned languages, but it is more important to do so because +invoices will be printed and sent to them. + +The credit limit field can be used to assign an amount that one is willing to do +for a customer on credit. + +\subsubsection{Customer Price Matrix} +The price list button can be used to enter specific discounts to the customer, +and groups of customers can be assigned a pricegroup for the purpose of offering +specific discounts on specific parts to the customer. Such discounts can be +temporary or permanent. + +\subsection{AR Transactions} +AR Transactions are where one can add moneys owed the business by customers. +One can associate these transactions with income accounts, and add payments if +the item is paid when the invoice is issued. + +The PO number field is used to track the PO that the customer sent. This makes +it easier to find items when a customer is asking for clarification on a bill, +for example. + +\subsection{AR Invoices} +AR Invoices are designed to provide for the delivery of goods and services to +customers. One would normally issue these invoices at the time when the +everything has been done that is necessary to get paid by the customer. + +As with AP invoices, one can search for matches to partial part numbers and +descriptions, and enter initial payments at this screen. + +\subsection{Cash Receipt} +The Cash-\textgreater Receipt screen allows you to accept prepayments from customers or pay +single or multiple invoices after they have been posted. One can print a +receipt, however the current templates seem to be based on check printing +templates and so are unsuitable for this purpose. This presents a great +opportunity for improvement. + +\subsubsection{Cash Receipts for multiple customers} +The cash-\textgreater receipts screen allows you to accept payments on all open customer +invoices of all customers at once. One could print (directly to a printer only) +all receipts to be sent out if this was desired. + +\subsection{AR Transaction Reporting} + +The AR Outstanding report is almost identical to the AP Outstanding report and +is not covered in any detail in this document. + +\subsubsection{AR Transactions Report} +This is almost identical to the AP Transactions Report. + +If a customer's PO has been associated with this transaction, one can search +under this field as well. + +\subsubsection{AR Aging Report} +This report is almost identical to the AP Aging report, with the exception that +one can print up statements for customer accounts that are overdue. One more +application is to calculate interest based on balance owed so that these can be +entered as AR transactions associated with the customer. + +\subsection{Customer Reporting} +These reports are almost identical tot he AP Vendor reports and are not +discussed in these notes. + +\section{Projects} +\subsection{Project Basics} +A project is a logical collection of AR and AP transactions, orders, and the +like that allow one to better manage specific service or product offerings. +Ledger-SMB does not offer comprehensive project management capabilities, and +projects are only used here as they relate to accounting. + +One can also add translated descriptions to the project names as well. + +\subsection{Timecards} +Timecards allow one to track time entered on specific services. These can then +be used to generate invoices for the time entered. + +The non-chargeable is the number of hours that are not billed on the invoice. + +One can then generate invoices based on this information. + +The project field is not optional. + +\subsection{Projects and Invoices} +One can select the project id for line items of both AR and AP invoices. These +will then be tracked against the project itself. + +\subsection{Reporting} +\subsubsection{Timecard Reporting} + +The Timecard Report allows one to search for timecards associated with one or +more projects. One can then use the total time in issuing invoices (this is not +automated yet). + +\subsubsection{Project Transaction Reporting} + +The Standard or GIFI options can be used to create different reports (for +example, for Canadian Tax reporting purposes). + +This report brings up a summary that looks sort of like a chart of accounts. Of +one clicks on the account numbers, one can see the transactions associated with +the project. + +\subsubsection{List of Projects} + +This provides a simple way of searching for projects to edit or modify. + +\subsection{Possibilities for Using Projects} +\begin{itemize} +\item One can use them similar to departments for tracking work done for a +variety of customers. +\item One can use them for customer-specific projects, such as this training. +\end{itemize} +\section{Quotations and Order Management} + +This unit will introduce the business processes that Ledger-SMB allows. These +processes are designed to allow various types of businesses to manage their +orders allow for rudimentary customer relationship management processes to be +built around this software. In this module, we will introduce the work flow +options that many businesses may use in their day-to-day use of the software. + +\subsection{Sales Orders} +Sales orders represent orders from customers that have not been delivered or +shipped yet. These orders can be for work in the future, or for back ordered +products, or work in progress. A sales order can be generated form an AR +invoice or from a quotation automatically. + +\subsection{Quotations} +Quotations are offers made to a customer but to which the customer has not +committed to the work. Quotations can be created from Sales orders or AR +Invoice automatically. + +\subsection{Shipping} +The Shipping module (Shipping-\textgreater Shipping) allows one to ship portions or +entireties of existing sales orders, printing pick lists and packing slips. + +One can then generate invoices for those parts that were shipped. + +In general, one will be more likely to use these features if they have multiple +warehouses that they ship from. More likely most customers will just generate +invoices from orders. + +\subsection{AR Work Flow} +\subsubsection{Service Example} + +A customer contacts your firm and asks for a quote on some services. Your +company would create a quotation for the job and email it to the customer or +print it and mail it. Once the customer agrees to pay, one creates an order +from the quotation. + +When the work is completed, the order is converted into a sales invoice and this +is presented to the customer as a bill. + +Note that in some cases, this procedure may be shortened. If the customer +places an order without asking for a quotation and is offered a verbal quote, +then one might merely prepare the order. + +\begin{figure}[hbtp] +\caption{Simple AR Service Invoice Workflow Example} +\input{simple_ar_dataflow} +\end{figure} + +\subsubsection{Single Warehouse Example} + +A customer contacts your firm and asks for a quotation for shipping a part. You +would create the quotation and when you get confirmation, convert it to an +order. Once the parts are in place you could go to shipping and ship the part. + +The billing department can then generate the invoice from the sales order based +on what merchandise has been shipped and mail it to the customer. + +Note that this requires that you have the part in your inventory. + +\begin{figure}[hbtp] +\caption{AR Workflow with Shipping} +\input{ar_workflow_ship} +\end{figure} + +\subsubsection{Multiple Warehouse Example} +A customer contacts your firm and asks for a quotation for a number of different +parts. You would create a quotation and when you get confirmation, convert it +to an order. When you go to ship the item, you would select the warehouse in +the drop-down menu, and select the parts to ship. One would repeat with other +warehouses until the entire order is shipped. + +Then the billing department would go to the sales order and generate the +invoice. It would then be mailed to the customer. + +\begin{figure}[hbtp] +\caption{Complex AR Workflow with Shipping} +\input{ar_workflow_complex} +\end{figure} + +\subsection{Requests for Quotation (RFQ)} +A request for quotation would be a formal document one might submit to a vendor +to ask for a quote on a product or service they might offer. These can be +generated from Purchase Orders or AP Invoices + +\subsection{Purchase Orders} +A purchase order is a confirmation that is issued to the vendor to order the +product of service. Many businesses will require a purchase order with certain +terms in order to begin work on a product. These can be generated from RFQ's or +AP Invoices. + +\subsection{Receiving} + +The Shipping-\textgreater Receiving screen allows you to track the parts +received from an existing purchase order. Like shipping, it does not post an +invoice but tracks the received parts in the order. + +\subsection{AP Work Flow} +\subsubsection{Bookkeeper entering the received items, order completed in full} + +Your company inquires about the price of a given good or service from another +firm. You submit an RFQ to the vendor, and finding that the price is +reasonable, you convert it to an order, adjust the price to what they have +quoted, and save it. When the goods are delivered you convert the +order into an AP invoice and post it. + + +\begin{figure}[hbtp] +\caption{Simple AP Workflow} +\input{simple_ap_workflow} +\end{figure} + +\subsubsection{Bookkeeper entering received items, order completed in part} + +Your company inquires about the price of a given good or service from another +firm, You submit an RFQ to the vendor, and finding that the price is +acceptable, you convert it into an order, adjusting the price to what they have +quoted, and save it. When some of the goods are received, you open up the +purchase order, enter the number of parts received, convert that order into +an invoice, and post it. Repeat until all parts are received. + +\begin{figure}[hbtp] +\caption{AP Workflow with Receiving} +\input{ap_workflow_ship} +\end{figure} + +\subsubsection{Receiving staff entering items} + +Your company inquires about the price of a given good or service from another +firm, You submit an RFQ to the vendor, and finding that the price is +acceptable, you convert it into an order, adjusting the price to what they have +quoted, and save it. When some or all of the goods are received, the receiving +staff goes Shipping-Receiving, locates the purchase order, and fills in the +number of items received. + +The bookkeeper can then determine when all items have been received and post the +invoice at that time. + +\begin{figure}[hbtp] +\caption{Complex AP Workflow} +\input{ap_workflow_complex} +\end{figure} + +\subsection{Generation and Consolidation} +\subsubsection{Generation} +The Generation screen allows you to generate Purchase Orders based on sales +orders. One selects the sales orders one wants to use, and clicks "Generate +Purchase Orders." Then one selects clicks on the parts to order, adjusts the +quantity if necessary, and clicks "Select Vendor." This process is repeated +for every vendor required. Then the Generate Orders button is clicked. + +\subsubsection{Consolidation} +One can consolidate sales and/or purchase orders using this screen. For the +consolidation to work you must have more than one order associated with the +relevant customer or vendor. + +\subsection{Reporting} +The reporting functionality in the order management is largely limited to the +ability to locate purchase orders, sales orders, RFQ's, and quotations. + +\subsection{Shipping Module: Transferring Inventory between Warehouses} +One can transfer inventory between warehouses if necessary by using the +Shipping-\textgreater Transfer Inventory screen. + +\section{HR} +The HR module is currently limited to tracking employees for and their start and +end dates. It has very little other functionality. One could build payroll +systems that could integrate with it however. + +\section{POS} + +The Point of Sale screen is still fairly rudimentary, and it is one of the least +mature aspects of Ledger-SMB. It is suitable for small retail environments at +the moment but not much else. + +\subsection{Sales Screen} +The sales screen looks very much like a normal invoice entry screen with a few +differences. + +\begin{itemize} +\item The discount text field is not available, nor is the unit field.. +\item The next part number is automatically focused when the data loads for +rapid data entry. +\item Hot keys for the buttons are Alt-U for update, Alt-P for print, Alt-O for +post, and Alt-R for print and post. +\item Part Groups appear at the bottom of the screen. +\end{itemize} + +\subsection{Possibilities for Data Entry} +\begin{itemize} +\item Barcode scanners can be used to scan items in as they are being rung in. +\item One could use touch screens, though this would ideally require some custom +stylesheets to make it efficient. +\end{itemize} + +\subsection{Hardware Support} +As Ledger-SMB is a web-based application, the web browser usually does not allow +the page to write to arbitrary files. Therefore hardware support for pole +displays, etc. is not readily possible from the application itself. In some +cases, there are add-on packages (such as SL-POS) which offer some additional +hardware options via simple additional networking programs. + +Notes for specific types of hardware are as follows: + +\begin{description} +\item[Touch screens:] The default stylesheet is not really usable from a +touchscreen as the items are often too small. One would need to modify the +stylesheets to ensure that the relevant items would be reasonable. Setting down +the resolution would also help. +\item[Receipt Printers:] ESC/POS printers generally work in text mode. Control +sequences can be embedded in the template as necessary. +\item[Pole Displays:] Generally are unsupported in Ledger-SMB without add-on +patches and special network clients. +\item[Cash Drawers:] These should be attached to the printer. The control codes +can then be embedded in the invoices so that the drawer opens whenever an +invoice is printed. +\item[Barcode Scanners:] Most customers use decoded barcode scanners through a +keyboard wedge interface. This allows them to scan items as if they were typing +them on the keyboard. +\end{description} + +\subsection{Reports} +\subsubsection{Open Invoices} +The POS-\textgreater Open screen allows one to find any POS receipts that are +not entirely paid off. + +\subsubsection{Receipts} +The POS-\textgreater Receipts screen allows one to bring up a basic record of +the POS terminals. It is not sufficient for closing the till, however, though +it may help for reconciliation. + +The till column is the last component or octet of the terminal's IP address. +Therefore it is a good idea to try to avoid having IP addresses where the last +octet is the same. + +All entries are grouped by date and source in this report. + +\section{General Ledger} +\subsection{GL Basics} + +The General Ledger is the heart of Ledger-SMB. Indeed, Ledger-SMB is designed +to be as close as possible to a software equivalent of a paper-based accounting +program (but with no difference between the General Ledger and General Journal). + +\subsubsection{Paper-based accounting systems and the GL} + +In order to understand the principle of the General Ledger, one must have a +basic understanding of the general process of bookkeeping using double-entry +paper-based accounting systems. + +Normally when a transaction would be recorded, it would first be recorded in the +"General Journal" which would contain detailed information about the +transaction, notes, etc. Then the entries from the General Journal would be +transcribed to the General Ledger, where one could keep closer tabs on what was +going on in each account. + +In the general journal, all transactions are listed chronologically with +whatever commentary is deemed necessary, while in +the general ledger each account has its own page and transactions are recorded +in a simple and terse manner. The General Journal is the first place the +transaction is recorded and the General Ledger is the last. + +At the end of the accounting period, the GL transactions would be summarized +into a trial balance and this would be used for creating financial statements +and closing the books at the end of the year. + +\subsubsection{Double Entry Examples on Paper} + +Let us say that John starts his business with an initial investment of \$10,000. + +This is recorded in the General Journal as follows (in this example, suppose it +is page 1): + +\begin{tabular}{|l|l|l|r|r|} +\hline +Date & Accounts and Explanation & Ref & DEBIT & CREDIT \\ +\hline +March 1 & Checking Account & 1060 & 10000.00 & \\ + & John Doe Capital & 3011 & & 10000.00\\ + & John Doe began a business & & & \\ + & with an investment of & & & \\ + & \$10000 & & & \\ +\hline +\end{tabular}\medskip + +This would then be transcribed into two pages of the General Ledger. The first +page might be the Checking Account page:\medskip + +\begin{tabular}{|l|l|l|r|l|l|l|r|} +\hline +DATE & EXPLANATION & REF. & DEBITS & DATE & EXPLANATION & REF. & CREDITS\\ +\hline +March 1 & & J1 & 10000.00 & & & & \\ +\hline +\end{tabular}\medskip + +On the John Doe Capital page, we would add a similar entry:\medskip + +\begin{tabular}{|l|l|l|r|l|l|l|r|} +\hline +DATE & EXPLANATION & REF. & DEBITS & DATE & EXPLANATION & REF. & CREDITS\\ +\hline + & & & & March 1 & & J1 & 10000.00\\ +\hline +\end{tabular}\medskip + +\subsubsection{The GL in Ledger-SMB} + +The paper-based accounting procedure works well when one is stuck with paper +recording requirements but it has one serious deficiency--- all of this +transcribing creates an opportunity for errors. + +Relational databases relieve the need for such transcription as it is possible +to store everything physically in a way similar to the way a General Journal is +used in the paper-based systems and then present the same information in ways +which are more closely related to the General Ledger book. + +This is the exact way that the General Ledger is used in Ledger-SMB. The actual +data is entered and stored as if it was a general journal, and then the data can +be presented in any number of different ways. + +All modules of Ledger-SMB that involve COA accounts store their data in the +General Ledger (it is a little more complex than this but this is very close to +the actual mechanism). + +\subsection{Cash Transfer} +The simplest form of GL entry in Ledger-SMB is the Cash-\textgreater Transfer +screen. This screen shows two transaction lines, and fields for reference, +department, description, and notes. + +The field descriptions are as follows: + +\begin{description} +\item[Reference] refers to the source document for the transfer. One can use +transfer sheets, bank receipt numbers, etc for this field. +\item[Description] is optional but really should be filled in. It ought to be a +description of the transaction. +\item[Notes] provide supplemental information for the transaction. +\item[FX] indicates whether foreign exchange is a factor in this transaction. +\item[Debit] indicates money going {\bf into} the asset account. +\item[Credit] indicates money coming {\bf out} of the asset account. +\item[Source] is the source document for that portion of the transaction. +\item[Memo] lists additional information as necessary +\item[Project] allows you to assign this line to a project. +\end{description} + +The credit and debit options seem to be the opposite of what one would think o +concerning one's bank account. The reason is that credits and debits are +recorded so as to balance any money that may be invested in or withdrawn from +the business. A debit to an asset account will be credited when money is +withdrawn from the business, for example. + +Also note that in this screen, when an item is updated, it will reduce the +number of lines to those already filled in plus an extra line for the new line +in the data entry. + +\subsection{GL Transactions} + +The GL Transaction screen (General Ledger-\textgreater Add Transaction) is +identical to the Cash Transfer screen with the exception that it starts with +nine instead of two lines. Otherwise, they are identical. + +Again, one must be careful with debits and credits. Often it is easy to get +confused. It is generally worth while to go back to the principle that one +tracks them with regard to their impact on the equity accounts. So expenses are +credits because they debit the equity accounts, and income is a debit because it +credits the retained earning equity account. + +\subsection{Payroll as a GL transaction} + +Currently payroll must be done as a GL transaction. The attempts to create a +payroll system that would ship with SL have largely stalled. + +Most customers running their businesses will have an idea of how to do this. + +\begin{figure}[hbtp] +\caption{Payroll as a GL Transaction (Purely fictitious numbers)} +\begin{tabular}{|l|r|r|} +\hline +Account & Debit & Credit \\ +5101 Wages and Salaries & 500 & \\ +2032 Accrued Wages & & 450 \\ +2033 Fed. Income Tax wthd & & 30 \\ +2034 State Inc. Tax. wthd & & 15 \\ +2035 Social Security wthd & & 3 \\ +2036 Medicare wthd & & 2 \\ +2032 Accrued Wages & 450 & \\ +1060 Checking Acct & & 450 \\ +\hline +\end{tabular} +\end{figure} + + +\subsection{Reconciliation} + +To reconcile an account (say, when one would get a checking account statement), +one would go to cash/reconciliation, and check off the items that have cleared. +One can then attempt to determine where any errors lie by comparing the total on +the statement with the total that SL generates. + +This can be done for other accounts too, such as petty cash.\footnote{Petty cash +denotes a drawer of cash that is used to pay small expenses. When an expense is +paid, it is recorded on a slip of paper that is stored for reconciliation +purposes.} + +\subsection{Reports} + +The most flexible report in Ledger-SMB is the GL report because it has access to +the entire set of financial transactions of a business. Every invoice posted, +payment made or received, etc. can be located here. + +The search criteria include: + +\begin{description} +\item[Reference] is the invoice number, or other reference number associated +with the transaction. +\item[Source] is the field related to the source document number in a payment or +other transaction.\footnote{Source documents are things like receipts, canceled +checks, etc. that can be used to verify the existence and nature of a +transaction.} +\item[Memo] relates to the memo field on a payment +\item[Department] can be used to filter results by department. +\item[Account Type] can be used to filter results by type of account (Asset, +Liability, etc.) +\item[Description] can be used to filter out by GL description or by +customer/vendor name. +\end{description} + +The actual format of the report looks more like what one would expect in a paper +accounting system's general journal than a general ledger per se. A +presentation of the data that is more like the paper general ledger is found in +the Chart of Accounts report. + +\subsubsection{GL as access to almost everything else} + +The GL reports can be used to do all manner of things. One can determine, for +example, which AP invoice or transaction was paid with a certain check number, +which invoice by a specific customer was paid by a specific check number. + +\section{Recurring Transactions} +Any transaction or invoice may be repeated a number of times in regular +intervals. To schedule any GL, AR, or AP transaction or invoice, click the +schedule button. + +In general the reference number should be left blank as this will force +Ledger-SMB to create a new invoice or transaction number for each iteration. +The rest of the options are self-explanatory. Note that a blank number if +iterations will result in no recurrences of the transaction. + +To process the recurring transactions, click on the Recurring Transactions +option on the main menu select the ones you want to process and click "Process +Transactions." + +\section{Financial Statements and Reports} +Financial statements and reports are a very important part of any accounting +system. Accountants and businesspeople rely on these reports to determine the +financial soundness of the business and its prospects for the next accounting +period. + +\subsection{Cash v. Accrual Basis} +Financial statements, such as the Income Statement and Balance Sheet can be +prepared either on a cash or accrual basis. In cash-basis accounting, the +income is deemed earned when the customer pays it, and the expenses are deemed +incurred when the business pays them. + +There are a number of issues with cash-basis accounting from a business point of +view. The most extreme is that one can misrepresent the wellbeing of a business +by paying a large expense after a deadline. Thus cash-basis accounting does not +allow one to accurately pair the income with the related expense as these are +recorded at different times. If one cannot accurately pair the income with the +related expense, then financial statements cannot be guaranteed to tell one much +of anything about the well-being of the business. + +In accrual basis accounting, income is considered earned when the invoice is +posted, +and expenses are considered incurred at the time when the goods or services are +delivered to the business. This way, one can pair the income made from the sale +of a product with the expense incurred in bringing that product to sale. This +pairing allows for greater confidence in business reporting. + +\subsection{Viewing the Chart of Accounts and Transactions} +The Reports--\textgreater Chart of Accounts will provide the chart of accounts +along with current totals in each account. + +If you click on an account number, you will get a screen that allows you to +filter out transactions in that account by various criteria. One can also +include AR/AP, and Subtotal in the report. + +The report format is similar to that of a paper-based general ledger, + +\subsection{Trial Balance} +\subsubsection{The Paper-based function of a Trial Balance} +In paper-based accounting systems, the accountant at the end of the year would +total up the debits and credits in every account and transfer them onto another +sheet called the trial balance. The accountant would check to determine that +the total debits and credits were equal and would then transfer this information +onto the financial statements. It was called a trial balance because it was the +main step at which the error-detection capabilities of double-entry accounting +systems were used. + +\subsubsection{Running the Trial Balance Report} +This report is located under Reports --\textgreater Trial Balance. One can +filter out items by date, accounting period, or department. One can run the +report by accounts or using GIFI classifications to group accounts together. + +From this report, you can click on the account number and see all transactions +on the trial balance as well as whether or not they have been reconciled. + +\subsubsection{What if the Trial Balance doesn't Balance?} +If the trial balance does not balance, get technical support immediately. This +usually means that transactions were not entered properly. Some may have been +out of balance, or some may have gone into non-existent accounts (believe it or +not, Ledger-SMB does not check this latter issue). + +\subsubsection{Trial Balance as a Summary of Account Activity} +The trial balance offers a glance at the total activity in every account. It +can provide a useful look at financial activity at a glance for the entire +business. + +\subsubsection{Trial Balance as a Budget Planning Tool} +By filtering out departments, one can determine what a department earned and +spent during a given financial interval. This can be used in preparing budgets +for the next accounting period. + +\subsection{Income Statement} +The Income Statement is another tool that can be used to assist with budgetary +planning as well as provide information on the financial health of a business. + +The report is run from Reports--\textgreater Income Statement. The report +preparation screen shows the following fields: + +\begin{description} +\item[Department] allows you to run reports for individual departments. This is +useful for budgetary purposes. +\item[Project] allows you to run reports on individual projects. This can show +how profitable a given project was during a given time period. +\item[From and To] allow you to select arbitrary from and to dates. +\item[Period] allows you to specify a standard accounting period. +\item[Compare to fields] allow you to run a second report for comparison +purposes for a separate range of dates or accounting period. +\item[Decimalplaces] allows you to display numbers to a given precision. +\item[Method] allows you to select between accrual and cash basis reports. +\item[Include in Report] provides various options for reporting. +\item[Accounts] allows you to run GIFI reports instead of the standard ones. +\end{description} + +The report shows all income and expense accounts with activity during the period +when the report is run, the balances accrued during the period, as well as the +total income and expense at the bottom of each section. The total expense is +subtracted from the total income to provide the net income during the period. +If there is a loss, it appears in parentheses. + +\subsubsection{Uses of an Income Statement} +The income statement provides a basic snapshot of the overall ability of the +business to make money. It is one of the basic accounting statements and is +required, for example, on many SEC forms for publicly traded firms. + +Additionally, businessmen use the income statement to look at overall trends in +the ability of the business to make money. One can compare a given month, +quarter, or year with a year prior to look for trends so that one can make +adjustments in order to maximize profit. + +Finally, these reports can be used to provide a look at each department's +performance and their ability to work within their budget. One can compare a +department or project's performance to a year prior and look for patterns that +can indicate problems or opportunities that need to be addressed. + +\subsection{Balance Sheet} +The balance sheet is the second major accounting statement supported by +Ledger-SMB. The balance sheet provides a snapshot of the current financial +health of the business by comparing assets, liabilities, and equity. + +In essence the balance sheet is a statement of the current state of owner +equity. Traditionally, it does not track changes in owner equity in the same +way the Statement of Owner Equity does. + +The Balance Sheet report preparation screen is much simpler than the Income +Statement screen. Balance sheets don't apply to projects, but they do apply to +departments. Also, unlike an income statement, a balance sheet is fixed for a +specific date in time. Therefore one does not need to select a period. + +The fields in creating a balance sheet are: + +\begin{description} +\item[Department] allows you to run separate balance sheets for each department. +\item[As at] specifies the date. If blank this will be the current date. +\item[Compare to] specifies the date to compare the balance sheet to. +\item[Decimalplaces] specifies the number of decimal places to use. +\item[Method] selects between cash and accrual basis. +\item[Include in report] allows you to select supplemental information on the +report. +\item[Accounts] allows you to select between standard and GIFI reports. +\end{description} + +The balance sheet lists all asset, liability, and equity accounts with a +balance. Each category has a total listed, and the total of the equity and +liability accounts is also listed. + +The total assets should be equal to the sum of the totals of the liability and +equity accounts. + +\subsection{What if the Balance Sheet doesn't balance?} + +Get technical support immediately, This may indicate that out of balance +transactions were entered or that transactions did not post properly. + +\subsection{No Statement of Owner Equity?} + +The Statement of Owner Equity is the one accounting statement that Ledger-SMB +does not support. However, it can be simulated by running a balance sheet at +the end of the time frame in question and comparing it to the beginning. One +can check this against an income statement for the period in question to verify +its accuracy. The statement of owner equity is not as commonly used now as it +once was. + +\section{The Template System} +Ledger-SMB allows most documents to be generated according to a template system. +This allows financial statements, invoices, orders, and the like to be +customized to meet the needs of most businesses. Company logos can be inserted, +the format can be radically altered, one can print letters to be included with +checks to vendors instead of the checks themselves, and the like. In the end, +there is very little that cannot be accomplished regarding modification of these +documents with the template system. + +One can define different templates for different languages, so that a customer +in Spain gets a different invoice than a customer in Canada. + +\subsection{Text Templates} +The only template that uses a text-only format is the POS receipt. This example +provides the simplest way to understand the template system. + +The first two lines are:\\ +\textless\%company align=center width=40\%\textgreater\\ +\textless\%address align=center width=40\%\textgreater\\ + +The first line tells Ledger-SMB to print the company name as passed to it via a +variable, centered, with a page width of 40 characters. The second line does +the same thing with the address. + +These variables are usually passed to the invoice using form fields (hidden or +otherwise) in the submitting web page. The printing script, however, can +disable some of these fields or add others via database lookups and the like. + +In all types of templates, variable substitution occurs between \textless\% and +\%\textgreater. One can optionally specify an alignment or a width but these +are really only useful in text templates. + +\subsection{HTML Templates} +The following templates exist in HTML format: + +\begin{itemize} +\item Income Statement +\item Balance Sheet +\item Invoice (AR) +\item AR Transaction +\item AP Transaction +\item Packing List +\item Pick List +\item Sales Order +\item Work Order +\item Purchase Order +\item Bin List +\item Statement +\item Quotation +\item RFQ +\item Time Card +\end{itemize} + +These templates can be edited by an HTML editor. However, it is generally +recommended that one back up templates first. The reason is that some HTML +editors will fully re-parse the HTML and save it back without what they see as +invalid tags. Most editors, however, will save the variable substitution tags +because similar tags are also used by Microsoft's active server pages. + +Finally, some editors are known to mangle formatting, so many problems can be +avoided by ensuring that one has a backup of the templates, especially if they +have already been customized. + +\subsection{\LaTeX\ Templates} +The following templates, by default, are available in \LaTeX\ : + +\begin{itemize} +\item Invoice +\item AR Transaction +\item AP Transaction +\item Packing List +\item Pick List +\item Sales Order +\item Work Order +\item Purchase Order +\item Bin List +\item Statement +\item Check +\item Receipt +\item Quotation +\item RFQ +\item Time Card +\end{itemize} + +\LaTeX\ templates allow one to generate PDF and postscript documents and print +directly to a postscript-enabled printer or print software (like CUPS). + +\LaTeX\ templates can be edited using a standard text editor (like vim or emacs), +or using a synchronous \LaTeX\ implementation such as LyX. + +\subsubsection{What is \LaTeX\ ?} +\LaTeX\ (pronounced LAY-tech) is an extension on the \TeX\ typesetting system. It +largely consists of a set of macros that allow one to focus on the structure of +the document while letting the \TeX\ engine do the heavy lifting in terms of +determining the optimal formatting for the page. \LaTeX\ is used in a large +number of academic journals (including those of the American Mathematics +Association). It is available at \url{http://www.tug.org}. + +Like HTML, \LaTeX\ uses plain text documents to store the formatting information +and then when the document is rendered, attempts to fit it onto a page. \LaTeX\ +supports the concept of stylesheets, allowing one to separate content from +format, and this feature is used in many higher-end applications, like journal +publication. + +Unlike HTML, \LaTeX\ is a complete though simple programming language that allows +one to redefine internals of the system for formatting purposes. + +This document is written in \LaTeX. + +\subsubsection{Using LyX to Edit \LaTeX\ Templates} +LyX is a synchronous \LaTeX\ editor that runs on Windows, UNIX/Linux, and +Mac OS X. It requires an installed \LaTeX-2e implementation and can be obtained +at \url{http://www.lyx.org}. Like the most common \LaTeX\ implementations, it is +open source. + +In \LaTeX, the \% sign is used to begin a comment. Therefore in order to edit +the documents effectively, you must convert the \% signs into another character +combination, such as @@@. This can be done with a sed script such as:\\ +sed -e "s$\vert$\%$\vert$@@@$\vert$ig" template.tex \textgreater\ +template-edit.tex \\ +Then when you are done:\\ +sed -e "$\vert$@@@$\vert$\%$\vert$ig" template-edit.tex \textgreater\ +template.tex + +One can edit the template-edit.tex without worrying about LyX disregarding lines +when it encounters a \%. + +\subsection{Customizing Logos} +\LaTeX\ requires different formats of logos depending on whether the document is +going to be generated as a PDF or as postscript. Postscript requires an +embedded postscript graphic, while PDF requires any type of graphic other than +embedded postscript. Usually one uses a PNG's for PDF's, though GIF's could be +used as well. The logo for a \LaTeX\ document resides in the users directory. + +HTML documents can have logos in many different formats. PNG's are generally +preferred for printing reasons. The image can be stored anywhere and merely +referenced in the HTML. + +Note: Always test the an invoice with an image on it to ensure that the rest of +the page format is not thrown off by it. + +\subsection{How are They Stored in the Filesystem?} +The template directory ("templates" in the root Ledger-SMB install directory) +contains all the root templates used by Ledger-SMB. These follow a naming +convention of COAType-templatename.ext where COAType is the type of dataset that +was created when the user was created, templatename is the name of the template, +and ext is either txt, html, or tex (for text, html, and \LaTeX\ respectively). + +Inside this directory are one or more subdirectories where the relevant +templates have been copied as default language templates for the user. Many +users can use the same user directory (which bears the name of the Ledger-SMB +username). Within this directory are more subdirectories for translated +templates, one for each language created. + +\subsection{Upgrade Issues} +When Ledger-SMB is upgraded, the templates are not replaced. This is designed +to prevent the upgrade script from overwriting changes made during the course of +customizing the templates. + +Occasionally, however, the data model changes in a way which can cause the +templates to stop printing certain information. When information that was +showing up before an upgrade stops showing up, one can either upgrade the +templates by copying the source template over the existing one, or one can edit +the template to make the change. + +\clearpage +\part{Technical Overview} +\section{Basic Architecture} + +Ledger-SMB is a web-based Perl program that interfaces with PostgreSQL using the +relevant Perl modules. The code is well partitioned, and the main operation +modules are written in an object oriented way. + +\subsection{The Software Stack} + +\begin{figure}[hbtp] +\label{fig-sl-stack} +\input{sl-stack.latex} +\caption{The Ledger-SMB software stack in a Typical Implementation} +\end{figure} + +Ledger-SMB runs in a Perl interpreter. I do not currently know if it is +possible to run it with Perl2C or other language converters to run in other +environments. However, except for high-capacity environments, Perl is a good +language choice for this sort of program. + +Ledger-SMB used to support DB2 and Oracle as well as PostgreSQL. However, +currently some of the functionality is implemented using PostgreSQL user-defined +functions. These would need to be ported to other database managers in order to +make the software work on these. It should not be too hard, but the fact that +it has not been done yet may mean that there is no real demand for running the +software under other RDBMS's. + +One can substitute other web servers for Apache. Normally Ledger-SMB is run as +a CGI program but it may be possible to run it in the web server process (note +that this may not be entirely thread-safe). + +The operating system can be any that supports a web server and Perl (since +PostgreSQL need not run on the same system). However, there are a few issues +running Ledger-SMB on Windows (most notably in trying to get Postscript +documents to print properly). + +On the client side, any web-browser will work. Currently, the layout is +different for Lynx (which doesn't support frames), and the layout is not really +useful under eLinks (the replacement for Lynx which does support frames). Some +functionality requires Javascript to work properly, though the application is +usable without these features. + +\subsection{Capacity Planning} +Some companies may ask how scalable Ledger-SMB is. In general, it is assumed +that few companies are going to have a need for a high-concurrency accounting +system. However, with all the features available in Ledger-SMB, the staff that +may have access to some of the application may be high enough to make the +question worthwhile. + +This question also becomes more important when companies might look at +integrating Ledger-SMB with a CRM solution, online store, or other environment. +This section looks at a number of the known issues and their solutions. + +\subsubsection{Scalability Strategies} +As Ledger-SMB is a fairly standard web-based application. However, sometimes +during upgrades, the database schema changes. In these cases, it becomes +impossible to use different versions of the software against the same database +version safely. Ledger-SMB checks the version of the database and if the +version is higher than the version of the software that is running, will refuse +to run. + +Therefore although one strategy might be to run several front-end web servers +with Ledger-SMB, in reality this can be a bit of a problem. One solution is to +take half of the front-end servers off-line while doing the initial upgrade, and +then take the other offline to upgrade when these are brought back online. + +The database manager is less scalable in the sense that one cannot just add more +database servers and expect to carry on as normal. However, aside from the +known issues listed below, there are few performance issues with it. If +complex reports are necessary, these can be moved to a replica database +(perhaps using Slony-I). + +If this solution is insufficient for database scalability, one might be able to +move staff who do not need real-time access to new entries onto a +PG-Pool/Slony-I cluster where new transactions are entered on the master and +other data is looked up on the replica. In certain circumstances, one can also +offload a number of other queries from the master database in order to minimize +the load. Ledger-SMB has very few issues in the scalability of the application. + +\subsubsection{Database Maintenance} +PostgreSQL uses a technique called Multi-version Concurrency Control (MVCC) to +provide a snapshot of the database at the beginning of a statement or +transaction (depending on the transaction isolation level). When a row is +updated, PostgreSQL leaves the old row in the database, and inserts a new +version of that row into the table. Over time, unless those old rows are +removed, performance can degrade as PostgreSQL has to search through all the old +versions of the row in order to determine which one ought to be the current one. + +Due to the way the SQL statements are executed in Ledger-SMB, most inserts will +also create a dead row. + +A second problem occurs in that each transaction is given a transaction id. +These id's are numbered using 32-bit integers. If the transaction id wraps +around (prior to 8.1), data from transactions that appear (due to the +wraparound) to be in the +future suddenly becomes inaccessible. This problem was corrected in PostgreSQL +8.1, where the database will refuse to accept new transactions if the +transaction ID gets too close to a wraparound. So while the problem is not as +serious in 8.1, the application merely becomes inaccessible rather than +displaying apparent data loss. Wraparound would occur after +about a billion transactions between all databases running on that instance of +PostgreSQL. + +Prior to 8.1, the main way to prevent both these problems was to run a periodic +vacuumdb command from cron (UNIX/Linux) or the task scheduler (Windows). In +8.1 or later, autovacuum capabilities are part of the back-end and can be +configured with the database manager. See the PostgreSQL documentation for +treatment of these subjects. + +In general, if performance appears to be slowly degrading, one should try to run +vacuumdb -z from the shell in order to attempt to reclaim space and +provide the planner with accurate information about the size and composition of +the tables. If this fails, then one can go to other methods of determining the +bottleneck and what to do about it. + +\subsubsection{Known issues} +The PostgreSQL planner assumes a minimum page size of ten pages for a physically +empty table. The reasoning behind this choice is that a table could grow +rapidly and one could end up with bad database performance if the planner +assumes a very small table. + +However, if you end up with joins between a very large table with millions of +rows and a physically empty table, one can end up with a very bad query plan. +In this case, the planner will choose a nested loop join and run through this +loop for every row in the large table. As a result, performance will suddenly +drop once the large table becomes too large to effectively do index scans of the +join criteria on both tables. This problem most often occurs when people have +no warehouses, departments, or projects defined and are running systems with a +large number of transactions (such as a point of sale environment). + +Last time I saw this problem, the server would wait for thirty seconds to +display a new point of sale screen while the server CPU activity would spike to +100\%. + +One solution is to define one warehouse, department, and project, and then run +vacuumdb -z from the shell to force the planner to acknowledge these tables as +single-row tables. The other option is to go into the source code and edit the +database queries to omit unused tables. + +\section{Customization Possibilities} +Ledger-SMB is designed to be customized relatively easily and rapidly. In +general, the source code is well written and compartmentalized. This section +covers the basic possibilities involving customization. + +\subsection{Brief Guide to the Source Code} +Ledger-SMB is an application with over 34000 lines of code. While it is not +possible to cover the entire application here, a brief overview of the source +code is in order. + +In the root of the install directory, one will find a setup.pl program, a number +of other .pl programs, and a number of directories. The setup.pl program is +used to update or install Ledger-SMB. The other .pl programs provide a basic +set of services for the framework (including authentication) and then pass the +work on to the data entry screen file in the bin directory. + +The bin directory contains another directory for each terminal type. The main +two offered are lynx and mozilla. Lynx would be used for web browsers that do +not support frames and is ideal for a text-mode VGA terminal. Mozilla is the +terminal type used for most other web browsers. The perl files within these +directories provides the user interface of the software. + +The css directory in the root install directory contains CSS documents to +provide various stylesheets one can select for changing various aspects of the +look and feel of the application. + +The locale directory contains translation files that Ledger-SMB uses to +translate between different languages. One could add translations to these +files if necessary. + +The SL directory is where the Perl modules reside that provide the core business +logic in Ledger-SMB. These modules provide functionality such as form handling, +email capabilities, and access to the database through its at least partially +object oriented API. + +Finally, the sql directory provides the database schemas and upgrade scripts. + +\subsection{Data Entry Screens} + +One can customize the data entry screens to optimize work flow, display +additional information, etc. + +\subsubsection{Examples} + +We set up hot keys for payment lines, automatically focused +the keyboard on the last partnumber field, removed separate print and post +buttons to ensure that invoices were always printed and posted together, and +removed the ability to print to the screen, and even the ability to scan items +in when an invoice was received (using a portable data terminal) and import this +data into Ledger-SMB. Finally we added the ability to reconcile the till online +in a paperless manner. + +For another customer, we added the ability to print AR invoices in plain text +format and added templates (based on the POS sales template) to do this. + +\subsection{Extensions} +One can add functionality to the Perl modules in the SL directory and often add +missing functions easily. + +\subsubsection{Examples} +For one customer, we added a module to take data from a portable data terminal +collected when inventory items were taken and use that to add shrinkage and loss +adjustments. We also extended the parts model to add a check id flag (for +alcohol sales) and added this flag to the user interface. + +For another customer, we added a complex invoice/packing slip tracking system +that allowed one to track all the printed documents associated with an order or +invoice. + +\subsection{Templates} +As noted before templates can be modified or extended, though sometimes this +involves extending the user interface scripts. Most templates are easy enough +to modify. +\subsubsection{Examples} +For one customer we added text-only invoices for AR and AP +transactions/Invoices and an ability to use Javascript in them to automatically +print them on load. + +\subsection{Reports} +The fact that all the data is available within the database manager is a huge +advantage of Ledger-SMB over Quickbooks and the like. The rapid development of +reports allows for one to easily develop reports of any sort within Ledger-SMB. + +\subsubsection{Examples} +For one customer, we developed a report of parts sold and received during +arbitrary time frames. The report allows one to go back and look up the invoices +involved. + +\section{Integration Possibilities} +An open database system and programming API allows for many types of +integration. There are some challenges, but in the end, one can integrate a +large number of tools. + +\subsection{Reporting Tools} +Any reporting tool which can access the PostgreSQL database can be used with +Ledger-SMB for custom reporting. These can include programs like Microsoft +Access and Excel (using the ODBC drivers), PgAccess (A PostgreSQL front-end +written in TCL/Tk with a similar feel to Access), Rekall, Crystal Reports, +OpenOffice and more. + +\subsubsection{Examples} +We have created spreadsheets of the summaries of activity by day and used the +ODBC driver to import these into Excel. Excel can also read HTML tables, so one +can use PostgreSQL to create an HTML table of the result and save it with a .xls +extension so that Windows opens it with Excel. These could then be served via +the same web server that serves Ledger-SMB. + +\subsection{Line of Business Tools on PostgreSQL} +Various line of business tools have been written using PostgreSQL in large part +due to the fact that it is far more mature than MySQL in areas relating to data +integrity enforcement, transactional processing, and the like. These tools can +be integrated with Ledger-SMB in various ways. One could integrate this program +with the HERMES CRM framework, for example. + +\subsubsection{Known Issues} +Ledger-SMB uses a single 'id' sequence across many tables. At the same time it +is expected that these tables do not have identical id values in their records +as they are used as a sort of pseudo-foreign key by the acc\_trans table which +stores the financial transaction information. + +If the integration solution does not keep this in mind, it is possible to create +a situation where the account transactions are ambiguously associated with a +number of different types of financial transactions. This would lead to a large +number of problems. + +\subsubsection{Strategies} +In general, it is advisable to run all such programs that benefit from +integration in the same database but under different schemas. This allows +PostgreSQL to become the main method of synchronizing the data in real time. +However, sometimes this can require dumping the database recreating the tables +etc. in a different schema and importing the data back into Ledger-SMB. + +One possibility for this sort of integration is to use database triggers to +replicate the data between the applications in real-time. This can avoid the +main issue of duplicate id's. One issue that can occur however relates to +updates. If one updates a customer record in HERMES, for example, how do we +know which record to update in Ledger-SMB? There are solutions to this problem +but they do require some forethought. + +A second possibility is to use views to allow one application to present the +data from the other as its own. This can be cleaner regarding update issues, +but it can also pose issues regarding duplicate id fields. + +\subsubsection{Examples} +Others have integrated L'ane POS and Ledger-SMB in order to make it work better +with touch screen devices. Still others have successfully integrated Ledger-SMB +and Interchange. In both cases, I believe that triggers were used to perform +the actual integration. + +\subsection{Line of Business Tools on other RDBMS's} +Often there are requests to integrate Ledger-SMB with applications like +SugarCRM, OSCommerce, and other applications running on MySQL or other database +managers. This is a far more complex field and it requires a great deal more +effort than integrating applications within the same database. + +\subsubsection{Strategies} +Ordinarily real-time integration is not always possible. MySQL does not support +the SQL extension SQL/MED (Management of External Data) so it is not possible to +replicate the data in real-time. Therefore one generally resorts to integrating +the system using time-based updates. Replication may be somewhat error-prone +unless the database manager supports triggers (first added to MySQL in 5.0) or +other mechanisms to ensure that +all changed records can be detected and replicated. In general, it is usually +advisable to add two fields to the record-- one that shows the insert time and +one that shows the last update. + +Additionally, I would suggest adding additional information to the Ledger-SMB +tables so that you can track the source record from the other application in the +case of an update. + +In general, one must write replication scripts that dump the information from +one and add it to the other. This must go both ways. + +\subsubsection{Integration Products and Open Source Projects} +While many people write Perl scripts to accomplish the replication, an open +source project exists called DBI-Link. This package requires PL/Perl to be +installed in PostgreSQL, and it allows PostgreSQL to present any data accessible +via Perl's DBI framework as PostgreSQL tables. DBI-Link can be used to allow +PostgreSQL to pull the data from MySQL or other database managers. + +DBI-Link can simplify the replication process by reducing the operation to a set +of SQL queries. + +\section{Customization Guide} +This section is meant to provide a programmer with an understanding of the +technologies enough information to get up to speed quickly and minimize the time +spent familiarizing themselves with the software. Topics in this section are +listed in order of complexity. As it appeals to a narrower audience than +previous discussions of this topic, it is listed separately. + +\subsection{General Information} +The main framework scripts (the ar.pl, ap.pl, etc. scripts found in the root of +the installation directory) handle such basic features as instantiating the form +object, ensuring that the user is logged in, and the like. They then pass the +execution off to the user interface script (usually in the bin/mozilla +directory). + +Ledger-SMB in many ways may look sort of object oriented in its design, but in +reality, it is far more data-driven than object oriented. The Form object is +used largely as a global symbol table and also as a collection of fundamental +routines for things like database access. It also breaks down the query string +into sets of variables which are stored in its attribute hash table. + +In essence one can and often will store all sorts of data structures in the +primary Form object. These can include almost anything. It is not uncommon to +see lists of hashes stored as attributes to a Form object. + +\subsection{Customizing Templates} +Templates are used to generate printed checks, invoices, receipts, and more in +Ledger-SMB. Often the format of these items does not fit a specific set of +requirements and needs to be changed. This document will not include LaTeX or +HTML instruction, but will include a general introduction to editing templates. +Also, this is not intended to function as a complete reference. + +Template instructions are contained in tags \textless\% and \%\textgreater. +The actual parsing is done by the parse\_template function in SL/Form.pm. + +\subsubsection{Page Breaks in \LaTeX} +The first tag one will see with \LaTeX\ templates is \textless\%pagebreak num1 +num2 num3\%\textgreater + +\begin{itemize} +\item num1 represents characters per line +\item num2 represents lines on first page +\item num3 represents lines on second page. +\end{itemize} + +The pagebreak block is terminated by \textless\%end pagebreak\%\textgreater +Any text within the pagebreak block is ignored by the template. + +\subsubsection{Conditionals} +\begin{itemize} +\item \textless\%if not varname\%\textgreater tells the parser to ignore + include the next block only if varname was posted by the submitting form + (or set via the form hash elsewhere in the scripts). The block ends with + \textless\%end varname\%\textgreater +\item \textless\%if varname\%\textgreater tells the parser to ignore the + block if varname was not posted in the submitting form (or set via the form + hash elsewhere in the scripts). The block ends with \textless\%end + varname\%\textgreater +\item Lines conditionals are otherwise ignored by the parser. +\item Conditionals cannot be nested, but IF's can be nested inside loops as of + 2.6.4 +\end{itemize} + +\subsubsection{Loops} +\textless\%foreach varname\%\textgreater is used to iterate through a list of +vars set by the user interface system (usually one of the files under +bin/mozilla (or otherwise). The block is repeated for each varname in a list. +Block ends with \textless\%end varname\%\textgreater + +\subsubsection{File Inclusion} +\begin{itemize} +\item Files may be included with the syntax \textless\%include + template\_name\%\textgreater where templatename is the name of the + template within the current template directory (usually + templates/\$username/) +\item Cannot be used with conditionals +\item Filenames cannot use slashes (/) or .. due to directory transversal + considerations. +\item Files can force other files to be included, but the same file cannot be + included more than once. +\end{itemize} + +\subsubsection{Cross-referencing and multiple passes of \LaTeX} +In \LaTeX\ cross-references require two passes with latex to resolve. This is +because the type is set page by page and the program really doesn't know on +which page a given reference will fall. This becomes an even larger issue where +floats are concerned as they can move between pages for formatting reasons. + +In rare cases, cross-references may point at incorrect pages even with two +passes (if the inclusion of the cross-reference data moves the object to another +page). In this case you will need to use three passes of \LaTeX\ in order to +have accurate references. + +Ledger-SMB as of the time of this writing (2.6.8) only makes one pass at the +\LaTeX\ file. To force it to make more than one pass, open Form.pm with your +favorite text editor. Look for the line: + +system("latex --interaction=nonstopmode +\$self-\textgreater$\lbrace$ tmpfile$\rbrace$\ +\textgreater\ \$ self-\textgreater$\lbrace$ tmpfile$\rbrace$ .err"); + +Duplicate this line for two passes, or add two copies if you need three passes. + +\subsubsection{Variable Substitution} +The following format is used for variable substitution: +\begin{itemize} +\item \textless\%varname options\%\textgreater Options are one or more + (whitespace separated) of: + \begin{itemize} + \item align=left/right/center + \item width=chars where chars is the width in characters before wrapping + \item offset=chars where chars is the number of spaces to (depending on +alignment). + \end{itemize} + +\end{itemize} + +\subsection{Customizing Forms} +Data entry forms and other user interface pieces are in the bin directory. In +Ledger-SMB 2.4 and below, most files were symlinked to the equivalent file in +the bin/mozilla directory. In 2.6 and later, symlinks are not generally used. + +Each module is identified with a two letter combination: ar, ap, cp, etc. +These combinations are generally explained in the comment headers on each file. + +Execution in these files begins with the function designated by the +form->$\lbrace$action$\rbrace$ variable. This variable is usually derived from +configuration parameters in the menu.ini or the name of the button that was +clicked on to submit the previous page. Due to localization requirements, the +following process is used to determine the appropriate action taken: + +The \$locale-\textgreater getsub routine is called. This routine checks the +locale package to determine if the value needs to be translated back into an +appropriate SL function. If not, the variable is lower-cased, and all spaces +are converted into underscores. + +In general there is no substitute for reading the code to understand how this +can be customized and how one might go about doing this. + +\subsection{Customizing Modules} + +The Perl Modules (.pm files) in the SL directory contain the main business logic +of the application including all database access. Most of these modules are +fairly easy to follow, and there is an effort to document all API's at the wiki +(\url{http://www.metatrontech.com/ledger-smb-wiki?APIReference}). + +Many of these modules have a fair bit of dormant code in them which was written +for forthcoming features, such as payroll and bills of materials. + +One can add a new module through the normal means and connect it to other +existing modules. + +\subsubsection{Database Access} +The \$form object provides two methods for accessing the database. The +\$form-\textgreater dbconnect(\%myconfig) method commits each individual +statement as its own transaction. The \$form-\textgreater +dbconnect\_noauto(\%myconfig) method requires a manual commit. Both these +functions are thin wrappers around the standard Perl DBI operations. + +\subsection{Examples} +\subsubsection{Adding a New Report for Sales Data} +One of our customers required a report of inventory activity during an arbitrary +time period. So we added this customization. This report required merely +adding a few functions to the rp.pl user interface script (bin/mozilla/rp.pl) +and slightly altering a few more. +However, as they eventually wanted to pull up invoices (AP and AR) containing +those part numbers, we also had to customize the AA.pm module to accept this +sort of filtering. + +The patch is available at +\url{http://www.metatrontech.com/downloads/sl-inv\_report-2.6.7.diff} and was +built against Ledger-SMB 2.6.7. + +\subsubsection{Truncating Number of Invoices on a Check Stub} + +One of our customers required an ability to truncate the list of invoices +printed on a stub so that an additional report could be printed as an +attachment. This patch required truncating the list of invoices in the +bin/mozilla/cp.pl file, and slightly patching the ledger-smb.conf to allow for +the number of listed invoices to be a runtime parameter. Finally a very small +modification was made to the template. + +The patch is available at +\url{http://www.metatrontech.com/downloads/sl-check-max-2.6.7.diff} + +\subsubsection{Adding the a Check ID flag for Alcohol Purchases} + +One of our customers is a retail store that sells alcoholic beverages. As the +law requires them to ask customers purchasing these beverages for ID, they +needed a reminder set to the screen when an alcoholic beverage was sold. + +To make this change, we added a field to the parts table of the database, had to +change a few aspects of the IC.pm to handle inserting and updating this field. +Then we modified the ps.pl to display a red banner on invoices which had +alcoholic beverages associated with them. + +This patch is part of SL-POS which can be downloaded at +\url{http://www.metatrontech.com/downloads/SL-POS-0.5.0.tar.gz} (note: this +patch has not been ported to Ledger-SMB 2.6.x yet). + +\clearpage +\part{Appendix} +\appendix +\section{Where to Go for More Information} + +There are a couple of relevant sources of information on Ledger-SMB in +particular. + +\begin{itemize} +\item The latest version of this document will always be advertised at +\url{http://www.metatrontech.com/projects/}. +\item We also maintain a community wiki with more information including +programming, customization, and links to other sites. The wiki can be found at +\url{http://www.metatrontech.com/ledger-smb-wiki} +\end{itemize} + +In addition, it is generally recommended that the main bookkeeper of a company +using Ledger-SMB work through at least one accounting textbook. Which textbook +is not as important as the fact that a textbook is used however. + +\section{Quick Tips} +\subsection{Understanding Shipping Addresses and Carriers} + +Each customer can have a default shipping address. This address is displayed +prominantly in the add new customer screen. To change the shipping address for +a single order, one can use the ship to button at the bottom of the quote, +order, or invoice screen. + +The carrier can be noted in the Ship Via field. However, this is a freeform +field and is largely used as commentary (or instructions for the shipping crew). + +\subsection{Handling bad debts} +In the event that a customer's check bounces or a collection requirement is +made, one can flag the customer's account by setting the credit limit to a +negative number. + +If a debt needs to be written off, one can either use the allowance method (by +writing it against the contra asset account of "Allowance for Bad Debts" or +using the direct writeoff method where it is posted as an expense. + +\section{Step by Steps for Vertical Markets} +\subsection{Common Installation Errors} +\begin{itemize} +\item Ledger-SMB is generally best installed in its own directory outside of the +wwwroot directory. While it is possible to install it inside the wwwroot +directory, the instructions and the faq don't cover the common problems here. +\item When the chart of accounts (COA) is altered such that it is no longer set +up with appropriate items, you can make it impossible to define goods and +services properly. In general, until you are familiar with the software, it is +best to rename and add accounts rather than deleting them. +\end{itemize} +\subsection{Retail With Light Manufacturing} +For purposes of this example we will use a business that assembles computers and +sells them on a retail store. +\begin{enumerate} +\item Install Ledger-SMB +\item Set preferences, and customize chart of accounts + \begin{enumerate} + \item Before customizing the COA it is often worth consulting an accountant. + \end{enumerate} +\item Define Goods, Labor, and Services as raw parts ordered from the vendors. + \begin{itemize} + \item These are located under the goods and services menu node. + \end{itemize} +\item Define assemblies + \begin{itemize} + \item These are also located under goods and services. + \item Component goods and services must be defined prior to creating assembly + \end{itemize} +\item Enter an AP Invoice to populate inventory with proper raw materials. + \begin{itemize} + \item One must generally add a generic vendor first. The vendor is added + under AP-\textgreater Vendors-\textgreater Add Vendor. + \end{itemize} +\item To pay an AP invoice like a check, go to cash->payment. Fill out + approrpiate fields and click print. + \begin{itemize} + \item Note that one should select an invoice and enter in the payment amount + in the appropriate line of the invoice list. If you add amounts to the + master amount list, you will find that they are added to the amount paid + on the invoice as a prepayment. + \item The source field is the check number. + \end{itemize} +\item Stock assemblies +\item One can use AR Invoices or the POS interface to sell goods and services. + \begin{itemize} + \item Sales Invoice + \begin{itemize} + \item Can be generated from orders or quotations + \item Cannot include labor/overhead except as part of an assembly + \item One can make the mistake of printing the invoice and forgetting to + post it. In this event, the invoice does not officially exist in the + accounting system. + \item For new customers, you must add the customer first (under + AR-\textgreater Customers-\textgreater Add Customer. + \end{itemize} + \item POS Interface + \begin{itemize} + \item Cannot include labor/overhead except as part of an assembly + \item Printing without posting is often even easier in the POS because of + the rapid workflow. Yet it is just as severe a problem. + \end{itemize} + \item Ecommerce and Mail Order Operations + \begin{itemize} + \item See the shipping workflow documentation above. + \end{itemize} + \item Customers are set up by going to AR-\textgreater Customers-\textgreater + Add Customer (or the + equivalent localized translation). The appropriate fields are filled + out and the buttons are used at the bottom to save the record and + optionally use it to create an invoice, etc. + \begin{itemize} + \item Saving a customer returns to the customer screen. After the + appropriate invoice, transaction, etc. is entered and posted, Ledger-SMB + will return to the add customer screen. + \end{itemize} + \end{itemize} +\item One can use the requirements report to help determine what parts need to +be ordered though one cannot generate PO's directly from this report. Note that +prior to 2.6.8 sales orders for assemblies are not properly tracked regarding. +\end{enumerate} + +Note, the needs of Ledger-SMB are mostly useful for light manufacturing +operations (assembling computers, for example). More manufacturing capabilities +are expected to be released in the next version. + +A custom assembly is a bit difficult to make. One must add the assembly prior +to invoice (this is not true of goods and services). If the assembly is based +on a different assembly but may cost more (due to non-standard parts) you can +load the old assembly using Goods and Services-\textgreater Reports-\textgreater +Assemblies and then make necessary changes (including to the SKU/Partnumber) and +save it as new. + +Then one can add it to the invoice. + +\section{Glossary} +\begin{description} +\item[BIC] Bank Identifier Code is often the same as the S.W.I.F.T. code. This +is a code for the bank a customer uses for automated money transfers. +\item[COGS] is Cost of Goods Sold. When an item is sold, then the expense of +its purchase is accrued as attached to the income of the sale. It is tracked as +COGS. +\item[Credit]: A logical transactional unit in double entry accounting. It is +the opposite of a debit. Credits affect different account types as +follows: + \begin{description} + \item[Equity]: Credits are added to the account when money is invested in the + business. + \item[Asset]: Credits are added when money is deducted from an asset account. + \item[Liability]: Credits are added when money is owed to the business + account. + \item[Income]: Credits are added when income is earned. + \item[Expense]: Credits are used to apply adjustments at the end of accounting + periods to indicate that not all the expense for an AP transaction has + been fully accrued. + \end{description} +\item[Debit]: A logical transactional unit in double entry accounting systems. +It is the opposite of a credit. Debits affect different account types as +follows: + \begin{description} + \item[Equity]: Debits are added when money is paid to business owners. + \item[Asset]: Debits are added when money is added to an account. + \item[Liability]: Debits are added when money that is owed is paid off. + \item[Income]: Debits are used to temporarily adjust income to defer unearned + income to the next accounting period. + \item[Expense]: Debits are added as expenses are incurred. + \end{description} +\item[IBAN] International Bank Account Number is related to the BIC and is used +for cross-border automated money transfers. +\item[List Price] is the recommended retail price. +\item[Markup] is the percentage increase that is applied to the last cost to get the sell price. +\item[ROP] Re-order point. Items with fewer in stock than this will show up on +short reports. +\item[Sell Price] is the price at which the item is sold. +\item[Source Document]: a paper document that can be used as evidence that a +transaction occurred. Source documents can include canceled checks, receipts, +credit card statements and the like. +\item[Terms] is the number of days one has to pay the invoice. Most businesses +abbreviate the terms as Net n where n is the number of days. For example, Net 30 +means the customer has 30 days to pay the net due on an invoice before it is +late and incurs late fees. +\end{description} + +\input{fdl.tex} +\end{document} + |