summaryrefslogtreecommitdiff
path: root/doc/manual/LedgerSMB-manual.tex
blob: 708de91f5734057c1793bff665b5ba72c9a6491a (plain)
  1. %% LyX 1.4.2 created this file. For more info, see http://www.lyx.org/.
  2. %% Do not edit unless you really know what you are doing.
  3. \documentclass[english]{article}
  4. \usepackage[T1]{fontenc}
  5. \usepackage[latin1]{inputenc}
  6. \IfFileExists{url.sty}{\usepackage{url}}
  7.                       {\newcommand{\url}{\texttt}}
  8. \newcommand{\version}{1.2}
  9. \makeatletter
  10. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%% LyX specific LaTeX commands.
  11. \providecommand{\LyX}{L\kern-.1667em\lower.25em\hbox{Y}\kern-.125emX\@}
  12. %% Bold symbol macro for standard LaTeX users
  13. \providecommand{\boldsymbol}[1]{\mbox{\boldmath $#1$}}
  14. %% Because html converters don't know tabularnewline
  15. \providecommand{\tabularnewline}{\\}
  16. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%% User specified LaTeX commands.
  17. \usepackage{metatron}
  18. \renewcommand{\abstractname}{Executive Summary}
  19. \title{Ledger-SMB Manual v. \version}
  20. \author{The LedgerSMB Core Team}
  21. \date{\today}
  22. \usepackage{babel}
  23. \makeatother
  24. \begin{document}
  25. \maketitle
  26. Copyright \copyright 2006 The LedgerSMB Core Team. Permission
  27. is granted to copy, distribute and/or modify this document under the
  28. terms of the GNU Free Documentation License, Version 1.2 or any later
  29. version published by the Free Software Foundation; with no Invariant
  30. Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of
  31. the license is included in the section entitled \char`\"{}GNU Free
  32. Documentation License\char`\"{} (Appendix \ref{fdl}).
  33. \tableofcontents{}
  34. \listoffigures
  35. \clearpage
  36. \part{Ledger-SMB and Business Processes}
  37. \section{Introduction to Ledger-SMB}
  38. \subsection{Why Ledger-SMB}
  39. \subsubsection{Advantages of Ledger-SMB}
  40. \begin{itemize}
  41. \item Flexibility and Central Management
  42. \item Accessibility over the Internet (for some users)
  43. \item Relatively open data format
  44. \item Integration with other tools
  45. \item Excellent accounting options for Linux users
  46. \item Open Source
  47. \item Flexible, open framework that can be extended or modified to fit
  48. your business.
  49. \item Security-conscious development community.
  50. \end{itemize}
  51. \subsubsection{Key Features}
  52. \begin{itemize}
  53. \item Accounts Receivable
  54. \begin{itemize}
  55. \item Track sales by customer
  56. \item Issue Invoices, Statements, Receipts, and more
  57. \item Do job costing and time entry for customer projects
  58. \item Manage sales orders and quotations
  59. \item Ship items from sales orders
  60. \end{itemize}
  61. \item Accounts Payable
  62. \begin{itemize}
  63. \item Track purchases and debts by vendor
  64. \item Issue RFQ's Purchase Orders, etc.
  65. \item Track items received from purchase orders
  66. \end{itemize}
  67. \item Budgeting
  68. \begin{itemize}
  69. \item Track expenditures and income across multiple departments
  70. \item Track all transactions across departments
  71. \end{itemize}
  72. \item Check Printing
  73. \begin{itemize}
  74. \item Customize template for any check form
  75. \end{itemize}
  76. \item General Ledger
  77. \item Inventory Management
  78. \begin{itemize}
  79. \item Track sales and orders of parts
  80. \item Track cost of goods sold using First In/First Out method
  81. \item List all parts below reorder point
  82. \item Track ordering requirements
  83. \item Track, ship, receive, and transfer parts to and from multiple warehouses
  84. \end{itemize}
  85. \item Localization
  86. \begin{itemize}
  87. \item Provide Localized Translations for Part Descriptions
  88. \item Provide Localized Templates for Invoices, Orders, Checks, and more
  89. \item Select language per customer, invoice, order, etc.
  90. \end{itemize}
  91. \item Manufacturing
  92. \begin{itemize}
  93. \item Track cost of goods sold for manufactured goods (assemblies)
  94. \item Create assemblies and stock assemblies, tracking materials on hand
  95. \end{itemize}
  96. \item Multi-company/Multiuser
  97. \begin{itemize}
  98. \item One isolated database per company
  99. \item Users can have localized systems independent of company data set
  100. \end{itemize}
  101. \item Point of Sale
  102. \begin{itemize}
  103. \item Run multiple cash registers against main Ledger-SMB installation
  104. \item Suitable for retail stores and more
  105. \item Credit card processing via TrustCommerce
  106. \item Supports some POS hardware out of the box including:
  107. \begin{itemize}
  108. \item Logic Controls PD3000 pole displays (serial or parallel)
  109. \item Basic text-based receipt printers
  110. \item Keyboard wedge barcode scanners
  111. \item Keyboard wedge magnetic card readers
  112. \item Printer-attached cash drawers
  113. \end{itemize}
  114. \end{itemize}
  115. \item Price Matrix
  116. \begin{itemize}
  117. \item Track different prices for vendors and customers across the board
  118. \item Provide discounts to groups of customers per item or across the board
  119. \item Store vendors' prices independent of the other last cost in the parts
  120. record
  121. \end{itemize}
  122. \item Reporting
  123. \begin{itemize}
  124. \item Supports all basic financial statements
  125. \item Easily display customer history, sales data, and additional information
  126. \item Open framework allows for ODBC connections to be used to generate
  127. reports using third party reporting tools.
  128. \end{itemize}
  129. \item Tax
  130. \begin{itemize}
  131. \item Supports Retail Sales Tax and Value Added Tax type systems
  132. \item Flexible framework allows one to customize reports to change the tax
  133. reporting framework to meet any local requirement.
  134. \end{itemize}
  135. \end{itemize}
  136. \subsection{Limitations of Ledger-SMB}
  137. \begin{itemize}
  138. \item No payroll module (Payroll must be done manually)
  139. \item Some integration limitations
  140. \item Further development/maintenance requires a knowledge of a relatively
  141. broad range of technologies
  142. \end{itemize}
  143. \subsection{System Requirements of Ledger-SMB}
  144. \begin{itemize}
  145. \item PostgreSQL
  146. \item A CGI-enabled Web Server (for example, Apache)
  147. \item Perl 5.8.x
  148. \item An operating system which supports the above software (usually Linux,
  149. though Windows, MacOS X, etc. do work)
  150. \item \LaTeX{}\ (optional) is required to create PDF or Postscript invoices
  151. \item The following CPAN modules:
  152. \begin{itemize}
  153. \item Data::Dumper
  154. \item Locale::Maketext
  155. \item Locale::Maketext::Lexicon
  156. \item MIME::Base64
  157. \item Digest::MD5
  158. \item HTML::Entities
  159. \item DBI
  160. \item DBD::Pg
  161. \item Math::BigFloat
  162. \item IO::File
  163. \item Encode
  164. \item Locale::Country
  165. \item Locale::Language
  166. \item Time::Local
  167. \item Cwd
  168. \item Config::Std
  169. \item MIME::Lite
  170. \end{itemize}
  171. \end{itemize}
  172. \section{User Account and Database Administration Basics}
  173. These functions are accessed via the admin.pl script in the
  174. installed directory of Ledger-SMB.
  175. \subsection{Companies and Datasets}
  176. Ledger-SMB stores its information in locale-specific data sets. When
  177. a dataset is created, it sets various defaults such as currency, a
  178. basic chart of accounts setup, and so forth. Note that the default
  179. setup is for Canada, where the author of the software resides.
  180. Datasets are stored as PostgreSQL databases. The application
  181. is designed with the idea that each dataset will represent exactly
  182. one company. If a customer is working with multiple companies, he/she
  183. must create a dataset to for each.
  184. When creating a dataset, the application asks for both a username and a
  185. superusername. If the superuser's information is not filled in, Ledger-SMB will
  186. attempt to populate an existing dataset, but if this information is filled in,
  187. the program will log into the PostgreSQL cluster with the superusername and
  188. password, create the database, and attempt to add Plpgsql to it.
  189. \subsection{How to Create a User}
  190. Users are created by going to the admin.pl page and clicking on \char`\"{}Add
  191. User.\char`\"{} One then fills out the form and when it is saved,
  192. the user is created.
  193. \subsection{Permissions}
  194. The permissions system is not rigorously enforced within Ledger-SMB,
  195. in the sense that the permissions API is generally not used in the
  196. application itself. Instead permissions are used to enable/disable
  197. menu options. Setting an enforcement of such permissions would require
  198. some custom programming at the present time. Most organizations, however,
  199. find that the current system is adequate.
  200. The checkboxes which are marked enable menu entries. Those that are
  201. unchecked disable those entries on the menu.
  202. \subsection{User Account Types}
  203. \begin{itemize}
  204. \item User is a general user of the system
  205. \item Managers often are able to see a larger amount of data
  206. \item Administrators have full access to the system
  207. \end{itemize}
  208. \subsection{Other Features}
  209. \begin{itemize}
  210. \item Lock System allows one to lock users out of the system while maintenance
  211. is performed. This is only necessary during upgrades or maintenance
  212. which results in the RDBMS being offline.
  213. \item Change Admin Password changes the administrative password.
  214. \item Logout terminates the admin session.
  215. \end{itemize}
  216. \section{Chart of Accounts}
  217. The Chart of Accounts provides a basic overview of the logical structure
  218. of the accounting program. One can customize this chart to allow for
  219. tracking of different sorts of information.
  220. \subsection{Introduction to Double Entry Bookkeeping}
  221. In order to set up your chart of accounts in LedgerSMB you will need to
  222. understand a bit about double entry bookkeeping. This section provides a
  223. brief overview of the essential concepts. There is a list of references
  224. for further reading at the end.
  225. \subsubsection{Business Entity}
  226. You don't want to mix your personal expenses and income with that of the
  227. business or you will not be able to tell how much money it is making (if
  228. any). For the same reason you will want to keep track of how much money
  229. you put into and take out of the business so you will want to set up a
  230. completely seperate set of records for it and treat it almost as if it had
  231. a life of its own.
  232. \subsubsection{Double Entry}
  233. Examples:
  234. \begin{itemize}
  235. \item When you buy you pay money and receive goods.
  236. \item When you sell you get money and give goods.
  237. \item When you borrow you get money and give a promise to pay it back.
  238. \item When you lend you give money and get a promise to pay it back.
  239. \item When you sell on credit you give goods and get a promise to pay.
  240. \item When you buy on credit you give a promise to pay and get goods.
  241. \end{itemize}
  242. You need to record both sides of each transaction: thus double entry.
  243. Furthermore, you want to organize your entries, recording those having to
  244. do with money in one place, value of goods bought and sold in another,
  245. money owed in yet another, etc. Hence you create accounts, and record each
  246. half of each transaction in an appropriate account. Of course, you won't
  247. have to actually record the amount in more than one place yourself: the
  248. program takes care of that.
  249. \subsubsection{Accounts}
  250. \begin{description}
  251. \item[Assets] Valuable stuff the business owns such as money and
  252. goods available for sale
  253. \item[Liabilities] Debts owned by the business such as bank loans and unpaid
  254. bills
  255. \item[Equity or Capital] What would be left for the owner if all the assets were
  256. converted to money and all the liabilities paid off ("Share Capital" on the
  257. LedgerSMB default chart of accounts: not to be confused with "Capital Assets".)
  258. \item[Revenue] Income from business activity: increases Equity
  259. \item[Expense] The light bill, the cost of goods sold, etc: decreases Equity
  260. \end{description}
  261. All other accounts are subdivisions of these. The relationship between the
  262. top-level accounts is often stated in the form of the Accounting Equation
  263. (don't worry: you won't have to solve it):
  264. Assets = Liabilities + Equity + (Revenue - Expense)
  265. You won't actually use this equation while doing your bookkeeping, but it's
  266. a useful tool for understanding how the system works.
  267. \subsubsection{Debits and Credits}
  268. Traditional paper accounting systems used a two-column form in which all
  269. increases went in one column and all deceases in the other. For asset and
  270. expense accounts increases went in the left column and decreases in the
  271. right. For liability and capital accounts decreases went in the left
  272. column and increases in the right. Looking at the accounting equation we
  273. see that assets are on the left, so it is logical that asset increases
  274. would go on the left. Libilities, capital, and revenue are on the right so
  275. it is logical that their increase would go on the right. Expenses,
  276. however, are on the right, so why do their increases go on the left?
  277. Because expenses are subtracted from the right side of the equation and so
  278. expense increases decrease the right side of the equation.
  279. Entries in the left column of the traditional form are called debits, while
  280. entries on the right are called credits. Neither is "negative".
  281. \begin{itemize}
  282. \item Debits increase assets
  283. \item Debits increase expense
  284. \item Credits increase liabilities
  285. \item Credits increase capital
  286. \item Credits increase revenue
  287. \end{itemize}
  288. Examples:
  289. You go to the bank and make a deposit. The teller tells you that he is
  290. going to credit your account. This is correct: your account is money the
  291. bank owes you and so is a liability from their point of view. Your deposit
  292. increased this liability and so they will credit it. They will make an
  293. equal debit to their cash account. When you return you will debit your
  294. bank deposits account because you have increased that asset and credit cash
  295. on hand because you have decreased that one.
  296. \subsubsection{Accrual}
  297. Early accounting systems were usually run on a cash basis. One generally did
  298. not consider money owed to affect the financial health of a company, so expenses
  299. posted when paid as did income.
  300. The problem with this approach is that it becomes very difficult or impossible
  301. to truly understand the exact nature of the financial health of a business. One
  302. cannot get the full picture of the financial health of a business because
  303. outstanding debts are not considered. Futhermore, this does not allow for
  304. revenue to be tied to cost effectively, so it becomes difficult to assess how
  305. profitable a given activity truly is.
  306. To solve this problem, accrual-based systems were designed. The basic principle
  307. is that income and expense should be posted as they are incurred, or accrued.
  308. This allows one to track income relative to expense for specific projects or
  309. operations, and make better decisions about which activities will help one
  310. maximize profitability.
  311. To show how these systems differ, imagine that you bill a customer for time and
  312. materials for a project you have just completed. The customer pays the bill
  313. after 30 days. In a cash based system, you would post the income at the time
  314. when the customer pays, while in an accrual system, the income is posted at the
  315. time when the project is completed.
  316. \subsubsection{References}
  317. \url{http://www.accounting-and-bookkeeping-tips.com/learning-accounting/accounting-basics-credit.htm}\\
  318. Discussion of debits and credits as well as links to other accounting subjects.\\
  319. \noindent \url{http://www.computer-consulting.com/accttips.htm}\\
  320. Discussion of double entry bookkeeping.\\
  321. \noindent \url{http://www.minnesota.com/~tom/sql-ledger/howtos/}\\
  322. A short glossary, some links, and a FAQ (which makes the "credit=negative
  323. number" error). The FAQ focuses on SQL-Ledger, LedgerSMB's ancestor.\\
  324. \noindent \url{http://bitscafe.com/pub2/etp/sql-ledger-notes\#expenses}\\
  325. Some notes on using SQL-Ledger (LedgerSMB's ancestor).\\
  326. \noindent \url{http://en.wikipedia.org/wiki/List\_of\_accounting\_topics}\\
  327. Wikipedia articles on accounting.\\
  328. \noindent \url{http://www.bized.ac.uk/learn/accounting/financial/index.htm}\\
  329. Basic accounting tutorial.\\
  330. \noindent \url{http://www.asset-analysis.com/glossary/glo\_index.html}\\
  331. Financial dictionary and glossary.\\
  332. \noindent \url{http://www.geocities.com/chapleaucree/educational/FinanceHandbook.html}\\
  333. Financial glossary.\\
  334. \noindent \url{http://www.quickmba.com/accounting/fin/}\\
  335. Explanation of fundamentals of accounting, including good discussions
  336. of debits and credits and of double-entry.
  337. \subsection{General Guidelines on Numbering Accounts}
  338. In general, most drop-down boxes in Ledger-SMB order the accounts
  339. by account number. Therefore by setting appropriate account numbers,
  340. one can affect the default values.
  341. A second consideration is to try to keep things under each heading
  342. appropriate to that heading. Thus setting an account number for a
  343. bank loan account in the assets category is not generally advisable.
  344. \subsection{Adding/Modifying Accounts}
  345. These features are listed under System-\textgreater Chart of Accounts.
  346. One can list the accounts and click on the account number to modify
  347. them or click on the \char`\"{}add account\char`\"{} option to create
  348. new accounts.
  349. \begin{itemize}
  350. \item Headings are just broad categories and do not store values themselves,
  351. while accounts are used to store the transactional information.
  352. \item One cannot have an account that is a summary account (like AR)
  353. and also has another function.
  354. \item GIFI is mostly of interest to Canadian customers but it can be used
  355. to create reports of account hierarchies.
  356. \end{itemize}
  357. \subsection{Listing Account Balances and Transactions}
  358. One can list the account balances via the Reports-\textgreater Chart
  359. of Accounts report. Clicking on the account number will provide a
  360. ledger for that account.
  361. \section{Administration}
  362. This section covers other (non-Chart of Accounts) aspects to the
  363. setup of the Ledger-SMB accounting package. These are generally accessed
  364. in the System submenu.
  365. \subsection{Taxes, Defaults, and Preferences}
  366. One of the new features in 1.2 is the modular sales tax system and the simple
  367. sales tax module. This allows one to install different tax modules and then
  368. select which taxes are applied by which programming modules. The sales tax
  369. module has access to everything on the submitted form so it is able to make
  370. complex determinations on what is taxable based on arbitrary criteria.
  371. The tax rules drop-down box allows one to select any installed tax module
  372. (LedgerSMB 1.2 ships only with the simple module), while the ordering is an
  373. integer which allows one to specify a tax run which occurs on the form after
  374. any rules with lower entries in this box. This allows for compounding of sales tax (for example, when PST applies to the total and GST as well).
  375. \subsubsection{Adding A Sales Tax Account}
  376. Sales Tax is collected on behalf of a state or national government
  377. by the individual store. Thus a sales tax account is a liability--
  378. it represents money owed by the business to the government.
  379. To add a sales tax account, create an account in the Chart of Accounts
  380. as a liability account, check all of the \char`\"{}tax\char`\"{} checkboxes.
  381. Once this account is created, one can set the tax amount.
  382. \subsubsection{Setting a Sales Tax Amount}
  383. Go to System-\textgreater Defaults and the tax account will be listed
  384. near the bottom of the page. The rate can be set there.
  385. \subsubsection{Default Account Setup}
  386. These accounts are the default accounts for part creation and foreign
  387. exchange tracking.
  388. \subsubsection{Currency Setup}
  389. The US accounts list this as USD:CAD:EUR. One can add other currencies
  390. in here, such as IDR (Indonesian Rupiah), etc. Currencies are separated
  391. by colons.
  392. \subsubsection{Sequence Settings}
  393. These sequences are used to generate user identifiers for quotations,
  394. invoices, and the like. If an identifier is not added, the next number
  395. will be used.
  396. A common application is to set invoices, etc. to start at 1000 in
  397. order to hide the number of issued invoices from a customer.
  398. Leading zeros are preserved. Other special values which can be embedded using
  399. $<$?lsmb ?$>$ tags include:
  400. \begin{description}
  401. \item[DATE] expands to the current date
  402. \item[YYMMDD] expands to a six-digit version of the date. The components of
  403. this date can be re-arranged in any order, so MMDDYY, DDMMYY,
  404. or even just MMYY are all options.
  405. \item[NAME] expands to the name of the customer or vendor
  406. \item[BUSINESS] expands to the type of business assigned to the customer or
  407. ventor.
  408. \item[DESCRIPTION] expands to the description of the part. Valid only for parts.
  409. \item[ITEM] expands to the item field. Valid only for parts.
  410. \item[PERISCOPE] expands to the partsgroup. Valid only for parts.
  411. \item[PHONE] expands to the telephoen number for customers and vendors.
  412. \end{description}
  413. \subsection{Audit Control}
  414. Auditability is a core concern of the architects of any accounting
  415. system. Such ensures that any modification to the accounting information
  416. leaves a trail which can be followed to determine the nature of the
  417. change. Audits can help ensure that the data in the accounting system
  418. is meaningful and accurate, and that no foul play (such as embezzlement)
  419. is occurring.
  420. \subsubsection{Explaining transaction reversal}
  421. In paper accounting systems, it was necessary to have a means to authoritatively
  422. track corrections of mistakes. The means by which this was done was
  423. known as \char`\"{}transaction reversal.\char`\"{}
  424. When a mistake would be made, one would then reverse the transaction
  425. and then enter it in correctly. For example, let us say that an office
  426. was renting space for \$300 per month. Let us say that they inadvertently
  427. entered it in as a \$200 expense.
  428. The original transaction would be:
  429. \begin{tabular}{l|r|r}
  430. Account &
  431. Debit &
  432. Credit \tabularnewline
  433. \hline
  434. 5760 Rent &
  435. \$200 &
  436. \tabularnewline
  437. 2100 Accounts Payable &
  438. &
  439. \$200\tabularnewline
  440. \end{tabular}
  441. The reversal would be:
  442. \begin{tabular}{l|r|r}
  443. Account &
  444. Debit &
  445. Credit \tabularnewline
  446. \hline
  447. 5760 Rent &
  448. &
  449. \$200\tabularnewline
  450. 2100 Accounts Payable &
  451. \$200 &
  452. \tabularnewline
  453. \end{tabular}
  454. This would be followed by re-entering the rent data with the correct
  455. numbers. This was meant to ensure that one did not erase data from
  456. the accounting books (and as such that erasing data would be a sign
  457. of foul play).
  458. Ledger-SMB has a capability to require such reversals if the business
  459. deems this to be necessary. When this option is enabled, existing
  460. transactions cannot be modified and one will need to post reversing
  461. transactions to void existing transactions before posting corrected
  462. ones.
  463. Most accountants prefer this means to other audit trails because it
  464. is well proven and understood by them.
  465. \subsubsection{Close books option}
  466. You cannot alter a transaction that was entered before the closing date.
  467. \subsubsection{Audit Trails}
  468. This option stores additional information in the database to help
  469. auditors trace individual transactions. The information stored, however,
  470. is limited and it is intended to be supplemental to other auditing
  471. facilities.
  472. The information added includes which table stored the record, which
  473. employee entered the information, which form was used, and what the
  474. action was. No direct financial information is included.
  475. \subsection{Departments}
  476. Departments are logical divisions of a business. They allow for budgets
  477. to be prepared for the individual department as well as the business
  478. as a whole. This allows larger businesses to use Ledger-SMB to meet
  479. their needs.
  480. \subsubsection{Cost v Profit Centers.}
  481. In general business units are divided into cost and profit centers.
  482. Cost centers are generally regarded as business units where the business
  483. expects to lose money and profit centers are where they expect to
  484. gain money. For example, the legal department in most companies is
  485. a cost center.
  486. One of the serious misunderstandings people run up against is that
  487. Ledger-SMB tends to more narrowly define cost and profit centers than
  488. most businesses do. In Ledger-SMB a cost center is any department
  489. of the business that does not issue AR transactions. Although many
  490. businesses may have cost centers (like technical support) where customer
  491. fees may subsidize the cost of providing the service, in Ledger-SMB,
  492. these are profit centers.
  493. Ledger-SMB will not allow cost centers to be associated with AR transactions.
  494. So if you want this functionality, you must create the department
  495. as a profit center.
  496. \subsection{Warehouses}
  497. Ledger-SMB has the ability to track inventory by warehouse. Inventory
  498. items can be moved between warehouses, and shipped from any warehouse
  499. where the item is in stock. We will explore this concept more later.
  500. \subsection{Languages}
  501. Languages allow for goods and services to be translated so that one
  502. can maintain offices in different countries and allow for different
  503. goods and service descriptions to be translated to different languages
  504. for localization purposes.
  505. \subsection{Types of Businesses}
  506. One can create types of businesses and then give them discounts across
  507. the board. For example, one might give a firm that uses one's services
  508. as a subcontractor a 10\% discount or more.
  509. \subsection{Misc.}
  510. \subsubsection{GIFI}
  511. GIFI is a requirement for Canadian customers. This feature allows
  512. one to link accounts with Canadian tax codes to simplify the reporting
  513. process. Some European countries now use a similar system.
  514. People that don't otherwise have a use for GIFI can use it to create reports
  515. which agregate accounts together.
  516. \subsubsection{SIC}
  517. Standard Industrial Classification is a way of tracking the type of
  518. business that a vendor or customer is in. For example, an accountant
  519. would have an SIC of 8721 while a graphic design firm would have an
  520. SIC of 7336. The classification is hierarchical so one could use this
  521. field for custom reporting and marketing purposes.
  522. \subsubsection{Overview of Template Editing}
  523. The templates for invoices, orders, and the like can be edited from
  524. within Ledger-SMB. The submenus within the System submenu such as
  525. HTML Templates, Text Templates and \LaTeX{} templates provide access
  526. to this functionality.
  527. \subsubsection{Year-end}
  528. Although the Year-end functionality in Ledger-SMB is very useful,
  529. it does not entirely make the process simple and painless. One must
  530. still manually enter adjustments prior to closing the books. The extent
  531. to which these adjustments are necessary for any given business is
  532. a matter best discussed with an accountant.
  533. The standard way books are normally closed at the end of the year
  534. is by moving all adjusted%
  535. \footnote{Adjustments would be entered via the General Ledger. The exact process
  536. is beyond the scope of this document, however.%
  537. } income and expenses to an equity account usually called \char`\"{}Retained
  538. Earnings.\char`\"{} Assets and liabilities are not moved. Equity drawing/dividend
  539. accounts are also moved, but the investment accounts are not. The
  540. reasoning behind this process is that one wants a permanent record
  541. of the amount invested in a business, but any dividends ought not
  542. to count against their recipients when new investors are brought on
  543. board.
  544. Ledger-SMB automatically moves all income and expense into the specified
  545. year-end/retained earnings account. It does not move the drawing account,
  546. and this must be done manually, nor does it automate the process of
  547. making adjustments.
  548. Contrary to its name, this function can close the books at any time,
  549. though this would likely be of limited use.
  550. \subsection{Options in the ledger-smb.conf}
  551. The ledger-smb.conf configures the software by assigning site-wide
  552. variables. Most of these should be left alone unless one knows what
  553. one is doing. However, on some systems some options might need to
  554. be changed, so all options are presented here for reference:
  555. \begin{description}
  556. \item[templates] is the directory where the templates are stored.
  557. \item[sendmail] is the command to use to send a message. It must read the
  558. email from standard input.
  559. \item[language] allows one to set the language for the login screen and
  560. admin page.
  561. \item[latex] tells Ledger-SMB whether \LaTeX{} is installed. \LaTeX{} is
  562. required for generating Postscript and PDF invoices and the like.
  563. \item[Environmental variables] can be set here too. One
  564. can add paths for searching for \LaTeX{}, etc.
  565. \item[Printers] section can be used to set a hash table of printers for the software.
  566. The primary example is\\
  567. $[$printers$]$\\
  568. Default = lpr\\
  569. Color = lpr -PEpson \\%
  570. However, this can use any program that can accept print documents
  571. (in Postscript) from standard input, so there are many more possibilities.
  572. \end{description}
  573. \section{Goods and Services}
  574. The Goods and Services module will focus on the definition of goods
  575. and services and the related accounting concepts.
  576. \subsection{Basic Terms}
  577. \begin{description}
  578. \item [{COGS}] is Cost of Goods Sold. When an item is sold, then the expense
  579. of its purchase is accrued as attached to the income of the sale.
  580. \item [{List}] Price is the recommended retail price.
  581. \item [{Markup}] is the percentage increase that is applied to the last
  582. cost to get the sell price.
  583. \item [{ROP}] is re-order point. Items with fewer in stock than this will
  584. show up on short reports.
  585. \item [{Sell}] Price is the price at which the item is sold.
  586. \end{description}
  587. \subsection{The Price Matrix}
  588. It is possible to set different prices for different groups of customers,
  589. or for different customers individually. Similarly, one can track
  590. different prices from different vendors along with the required lead
  591. time for an order.
  592. \subsection{Pricegroups}
  593. Pricegroups are used to help determine the discount a given customer
  594. may have.
  595. \subsection{Groups}
  596. Groups represent a way of categorizing POS items for a touchscreen
  597. environment. It is not fully functional yet, but is sufficient that
  598. with some stylesheet changes, it could be made to work.
  599. \subsection{Labor/Overhead}
  600. Labor/overhead is usually used for tracking manufacturing expenses.
  601. It is not directly billed to a customer. It is associated with an
  602. expense/Cost of Goods Sold (COGS) account.
  603. \subsection{Services}
  604. Services include any labor that is billed directly to the customer.
  605. It is associated with an expense/COGS account and an income account.
  606. Services can be associated with sales tax.
  607. \subsubsection{Shipping and Handling as a Service}
  608. One approach to dealing with shipping and handling is to add it as
  609. a service. Create a service called {}``Shipping and Handling'',
  610. with a sell price \$1 per unit, and a 0\% markup. Bill it as \$1 per
  611. unit. This allows one to add the exact amount of shipping and handling
  612. as necessary.
  613. \subsection{Parts}
  614. A part is any single item you might purchase and either might resell
  615. or use in manufacturing an assembly. It is linked to an expense/COGS
  616. account, an income account, and an inventory account. Parts can be
  617. associated with sales tax.
  618. \subsection{Assemblies and Manufacturing}
  619. Manufacturers order parts but they sell the products of their efforts.
  620. Ledger-SMB supports manufacturing using the concept of assemblies.
  621. An assembly is any product which is manufactured on site. It consists
  622. of a selection of parts, services, and/or labor and overhead. Assemblies
  623. are treated as parts in most other regards.
  624. However, one cannot order assemblies from vendors. One must instead
  625. order the components and stock them once they are manufactured.
  626. \subsubsection{Stocking Assemblies}
  627. One stocks assemblies in the Stock Assembly entry on the Goods and
  628. Services submenu. When an assembly is stocked the inventory is adjusted
  629. properly.
  630. The Check Inventory option will cause Ledger-SMB to refuse to stock
  631. an assembly if the inventory required to produce the assembly would
  632. drop the part below the reorder point.
  633. \subsection{Reporting}
  634. \subsubsection{All Items and Parts Reports}
  635. The All Items report provides a unified view of assemblies, parts, services,
  636. and labor for the company, while the Parts report confines it to parts.
  637. Types of reports are:
  638. \begin{description}
  639. \item [{Active}] lists all items not marked as obsolete.
  640. \item [{On}] Hand lists current inventory .
  641. \item [{Short}] Lists all items which are stocked below their ROP.
  642. \item [{Obsolete}] Lists all items which are marked as obsolete.
  643. \item [{Orphaned}] Lists all items which have never had a transaction associated
  644. with them.
  645. \end{description}
  646. One can also list these goods by invoice, order, or quotation.
  647. For best results, it is a good idea to enter some AR and AP data before
  648. running these reports.
  649. \subsubsection{Requirements}
  650. This report is designed to assist managers determine the quantities
  651. of goods to order and/or stock. It compares the quantity on hand with
  652. the activity in a given time frame and provides a list of goods which
  653. need to be ordered and the relevant quantity.
  654. \subsubsection{Services and Labor}
  655. This is similar to the Parts and All Items menu but only supports
  656. Active, Obsolete, and Orphaned reports.
  657. \subsubsection{Assemblies}
  658. This is similar to the Parts and All Items reports but it also provides
  659. an ability to list individual items in the assemblies as well.
  660. AP Invoices, Purchase Orders, and RFQ's are not available on this
  661. report.
  662. \subsubsection{Groups and Pricegroups}
  663. These reports provide a simple interface for locating groups and pricegroups.
  664. The report types are similar to what they are for services.
  665. \subsection{Translations}
  666. One can add translations so that they show up in the customer's native
  667. language in the issued invoice.
  668. To issue translations, one must have languages defined. One can then
  669. add translations to descriptions and part groups.
  670. \subsection{How Cost of Goods Sold is tracked}
  671. Cost of Goods Sold is tracked on a First-In, First-out (FIFO) basis.
  672. When a part is purchased, its cost is recorded in the database. The
  673. cost of the item is then added to the inventory asset account. When
  674. the good is sold, the cost of the item is moved to the cost of goods
  675. sold account.
  676. This means that one must actually provide invoices for all goods entered
  677. at their actual cost. If one enters in \$0 for the cost, the cost
  678. of goods sold will also be \$0 when the item is sold. We will cover
  679. this entire process in more depth after we cover the AP and AR units
  680. below.
  681. \section{AP}
  682. \subsection{Basic AP Concepts}
  683. The Accounts Payable module tracks all financial commitments that
  684. the company makes to other businesses. This includes rent, utilities,
  685. etc. as well as orders of goods and services.
  686. \subsection{Vendors}
  687. A vendor is any business that the company agrees to pay money to.
  688. One can enter vendor information under AP-\textgreater Vendors-\textgreater
  689. Add Vendor. The vendor list can be searched under AP-\textgreater
  690. Vendors-\textgreater Reports-\textgreater Search.
  691. Enter start and end-dates for each vendor. This will make searches
  692. and drop-down boxes faster when some vendors are no longer actively
  693. supporting your company.
  694. A few fields that need explanation are:
  695. \begin{description}
  696. \item [{BIC}] Bank Identifier Code is often the same as the S.W.I.F.T.
  697. code. This is a code for the bank a customer uses for automated money
  698. transfers.
  699. \item [{IBAN}] International Bank Account Number is related to the BIC
  700. and is used for cross-border automated money transfers.
  701. \item [{Terms}] is the number of days one has to pay the invoice.
  702. \item [{Vendor}] Number is automatically generated.
  703. \end{description}
  704. \subsection{AP Transactions}
  705. AP Transactions are generally used for items other than goods and
  706. services. Utilities, rent, travel expenses, etc. could be entered
  707. in as an AP transaction.
  708. If the item is paid partially or in full when the transaction is entered,
  709. one can add payments to the payment section.
  710. All other payments can and should be entered under cash payment (below).
  711. The PO Number and Order Number fields are generally used to track
  712. associations with purchase orders sent to vendors, etc. These fields
  713. can be helpful for adding misc. expenses to orders for reporting purposes.
  714. The department drop-down box appears when one has created one or more
  715. departments. A transaction is not required to be associated with a
  716. department, but one can use this feature for budget tracking.
  717. With AP Transactions, there is no option for internal notes. All notes
  718. will appear on any printed version of the transaction.
  719. Note: Printing a transaction does not post it. No data is committed
  720. until the invoice is posted.
  721. \subsection{AP Invoices}
  722. AP Invoices are used to enter in the receipt of goods and services.
  723. Goods and services are deemed entered into the inventory when they
  724. are invoiced.
  725. This screen is reasonably similar to the AP Transaction Screen, though
  726. the part entry section is a bit different.
  727. The AP Invoice section has a capacity to separate internal notes from
  728. notes printed on the invoice. Note, however, that since these are
  729. received invoices, it is rare that one needs this ability.
  730. Note that Ledger-SMB can search for partial part numbers or descriptions.
  731. Also if you have a group you can use this to select the part.
  732. To remove a line item from an invoice or order, delete the partnumber
  733. and click update.
  734. \subsubsection{Correcting an AP Invoice}
  735. If an invoice is entered improperly, the methods used to correct it
  736. will vary depending on whether transaction reversal is enforced or
  737. not. If transaction reversal is not enforced, one can simply correct
  738. the invoice or transaction and repost. Note, however, that this violates
  739. generally accepted accounting principles.
  740. If transaction reversal is in effect, one needs to create a duplicate
  741. invoice with exactly opposite values entered. If one part was listed as
  742. received, then one should enter a negative one for the quantity. Then one
  743. can enter the invoice number as the same as the old one. Add an R to the
  744. end to show that it is a reversing transaction. Once this is posted, one can
  745. enter the invoice correctly.
  746. \subsection{Cash payment And Check Printing}
  747. It is a bad idea to repost invoices/transactions just to enter a payment.
  748. The Cash-\textgreater Payment window allows one to enter payments against
  749. AP invoices or transactions.
  750. The printing capability can be used to print checks. The default template
  751. is NEBS 9085, though you can use 9082 as well (as Quickbooks does).
  752. The source field is used to store an identifying number of the source
  753. document, such as the check number. One must select the item to have
  754. it paid, and then enter the amount. One can then print a check.
  755. \subsubsection{Rapid Payment Entry Screen}
  756. One can also use the rapid payment entry screen to print multiple
  757. checks. However, this does not allow you to print the multiple checks
  758. to the screen as a separate document is created for each check. In
  759. this event, one must print directly to a printer as postscript.
  760. \subsection{Transaction/Invoice Reporting}
  761. \subsubsection{Transactions Report}
  762. This report is designed to help you locate AP transactions based on
  763. various criteria. One can search by vendor, invoice number, department,
  764. and the like. One can even search by the shipping method.
  765. The summary button will show what was placed where, while the details
  766. button will show all debits and credits associated with the transaction.
  767. To view the invoice, click on the invoice number. In the detail view,
  768. to view the account transactions as a whole, click on the account
  769. number.
  770. Open invoices are ones not fully paid off, while closed invoices
  771. are those that have been paid.
  772. \subsubsection{Outstanding Report}
  773. The outstanding report is designed to help you locate AP transactions
  774. that are not paid yet. The ID field is mostly useful for locating
  775. the specific database record if a duplicate invoice number exists.
  776. \subsubsection{AP Aging Report}
  777. This report can tell you how many invoices are past due and by how
  778. much.
  779. A summary report just shows vendors while a detail report shows individual
  780. invoices.
  781. \subsubsection{Tax Paid and Non-taxable Report}
  782. These reports have known issues. It is better to use the GL reports and filter
  783. accordingly.
  784. \subsection{Vendor Reporting}
  785. \subsubsection{Vendor Search}
  786. The Vendor Search screen can be used to locate vendors or AP transactions
  787. associated with those vendors.
  788. The basic types of reports are:
  789. \begin{description}
  790. \item [{All}] Lists all vendors
  791. \item [{Active}] Lists those vendors currently active
  792. \item [{Inactive}] Lists those vendors who are currently inactive. time
  793. frame.
  794. \item [{Orphaned}] Lists those vendors who do not have transactions associated
  795. with them. These vendors can be deleted.
  796. \end{description}
  797. One can include purchase orders, Requests for Quotations, AP invoices,
  798. and AP transactions on this report as well if they occur between the
  799. from and to dates.
  800. \subsubsection{Vendor History}
  801. This report can be used to obtain information about the past goods
  802. and services ordered or received from vendors. One can find quantities,
  803. partnumber, and sell prices on this report. This facility can be used
  804. to search RFQ's, Purchase Orders, and AP Invoices.
  805. \section{AR}
  806. \subsection{Customers}
  807. Customers are entered in using the AR-\textgreater Customers-\textgreater
  808. Add Customer menu.
  809. The salesperson is autopopulated with the current user who is logged
  810. in. Otherwise, it looks fairly similar to the Vendor input screen.
  811. Customers, like vendors can be assigned languages, but it is more
  812. important to do so because invoices will be printed and sent to them.
  813. The credit limit field can be used to assign an amount that one is
  814. willing to do for a customer on credit.
  815. \subsubsection{Customer Price Matrix}
  816. The price list button can be used to enter specific discounts to the
  817. customer, and groups of customers can be assigned a pricegroup for
  818. the purpose of offering specific discounts on specific parts to the
  819. customer. Such discounts can be temporary or permanent.
  820. \subsection{AR Transactions}
  821. AR Transactions are where one can add moneys owed the business by
  822. customers. One can associate these transactions with income accounts,
  823. and add payments if the item is paid when the invoice is issued.
  824. The PO number field is used to track the PO that the customer sent.
  825. This makes it easier to find items when a customer is asking for clarification
  826. on a bill, for example.
  827. \subsection{AR Invoices}
  828. AR Invoices are designed to provide for the delivery of goods and
  829. services to customers. One would normally issue these invoices at
  830. the time when the everything has been done that is necessary to get
  831. paid by the customer.
  832. As with AP invoices, one can search for matches to partial part numbers
  833. and descriptions, and enter initial payments at this screen.
  834. \subsection{Cash Receipt}
  835. The Cash-\textgreater Receipt screen allows you to accept prepayments
  836. from customers or pay single or multiple invoices after they have
  837. been posted. One can print a receipt, however the current templates
  838. seem to be based on check printing templates and so are unsuitable
  839. for this purpose. This presents a great opportunity for improvement.
  840. \subsubsection{Cash Receipts for multiple customers}
  841. The cash-\textgreater receipts screen allows you to accept payments
  842. on all open customer invoices of all customers at once. One could
  843. print (directly to a printer only) all receipts to be sent out if
  844. this was desired.
  845. \subsection{AR Transaction Reporting}
  846. The AR Outstanding report is almost identical to the AP Outstanding
  847. report and is not covered in any detail in this document.
  848. \subsubsection{AR Transactions Report}
  849. This is almost identical to the AP Transactions Report.
  850. If a customer's PO has been associated with this transaction, one
  851. can search under this field as well.
  852. \subsubsection{AR Aging Report}
  853. This report is almost identical to the AP Aging report, with the exception
  854. that one can print up statements for customer accounts that are overdue.
  855. One more application is to calculate interest based on balance owed
  856. so that these can be entered as AR transactions associated with the
  857. customer.
  858. \subsection{Customer Reporting}
  859. These reports are almost identical to the AP Vendor reports and are
  860. not discussed in these notes.
  861. \section{Projects}
  862. \subsection{Project Basics}
  863. A project is a logical collection of AR and AP transactions, orders,
  864. and the like that allow one to better manage specific service or product
  865. offerings. Ledger-SMB does not offer comprehensive project management
  866. capabilities, and projects are only used here as they relate to accounting.
  867. One can also add translated descriptions to the project names as well.
  868. \subsection{Timecards}
  869. Timecards allow one to track time entered on specific services. These
  870. can then be used to generate invoices for the time entered.
  871. The non-chargeable is the number of hours that are not billed on the
  872. invoice.
  873. One can then generate invoices based on this information.
  874. The project field is not optional.
  875. \subsection{Projects and Invoices}
  876. One can select the project id for line items of both AR and AP invoices.
  877. These will then be tracked against the project itself.
  878. \subsection{Reporting}
  879. \subsubsection{Timecard Reporting}
  880. The Timecard Report allows one to search for timecards associated
  881. with one or more projects. One can then use the total time in issuing
  882. invoices (this is not automated yet).
  883. \subsubsection{Project Transaction Reporting}
  884. The Standard or GIFI options can be used to create different reports
  885. (for example, for Canadian Tax reporting purposes).
  886. This report brings up a summary that looks sort of like a chart of
  887. accounts. Of one clicks on the account numbers, one can see the transactions
  888. associated with the project.
  889. \subsubsection{List of Projects}
  890. This provides a simple way of searching for projects to edit or modify.
  891. \subsection{Possibilities for Using Projects}
  892. \begin{itemize}
  893. \item One can use them similar to departments for tracking work done for
  894. a variety of customers.
  895. \item One can use them for customer-specific projects, such as this training.
  896. \end{itemize}
  897. \section{Quotations and Order Management}
  898. This unit will introduce the business processes that Ledger-SMB allows.
  899. These processes are designed to allow various types of businesses
  900. to manage their orders and allow for rudimentary customer relationship
  901. management processes to be built around this software. In this section,
  902. we will introduce the work flow options that many businesses may use
  903. in their day-to-day use of the software.
  904. \subsection{Sales Orders}
  905. Sales orders represent orders from customers that have not been delivered
  906. or shipped yet. These orders can be for work in the future, for
  907. back ordered products, or work in progress. A sales order can be generated
  908. form an AR invoice or from a quotation automatically.
  909. \subsection{Quotations}
  910. Quotations are offers made to a customer but to which the customer
  911. has not committed to the work. Quotations can be created from Sales
  912. orders or AR Invoice automatically.
  913. \subsection{Shipping}
  914. The Shipping module (Shipping-\textgreater Shipping) allows one to
  915. ship portions or entireties of existing sales orders, printing pick
  916. lists and packing slips.
  917. One can then generate invoices for those parts that were shipped.
  918. In general, one will be more likely to use these features if they
  919. have multiple warehouses that they ship from. More likely most customers
  920. will just generate invoices from orders.
  921. \subsection{AR Work Flow}
  922. \subsubsection{Service Example}
  923. A customer contacts your firm and asks for a quote on some services.
  924. Your company would create a quotation for the job and email it to
  925. the customer or print it and mail it. Once the customer agrees to
  926. pay, one creates a sales order from the quotation.
  927. When the work is completed, the sales order is converted into a sales
  928. invoice and this is presented to the customer as a bill.
  929. Note that in some cases, this procedure may be shortened. If the customer
  930. places an order without asking for a quotation and is offered a verbal
  931. quote, then one might merely prepare the sales order.
  932. %
  933. \begin{figure}[hbtp]
  934. \caption{Simple AR Service Invoice Workflow Example}
  935. \input{simple_ar_dataflow}
  936. \end{figure}
  937. \subsubsection{Single Warehouse Example}
  938. A customer contacts your firm and asks for a quotation for shipping
  939. a part. You would create the quotation and when you get confirmation,
  940. convert it to an order. Once the parts are in place you could go to
  941. shipping and ship the part.
  942. The billing department can then generate the invoice from the sales
  943. order based on what merchandise has been shipped and mail it to the
  944. customer.
  945. Note that this requires that you have the part in your inventory.
  946. %
  947. \begin{figure}[hbtp]
  948. \caption{AR Workflow with Shipping}
  949. \input{ar_workflow_ship}
  950. \end{figure}
  951. \subsubsection{Multiple Warehouse Example}
  952. A customer contacts your firm and asks for a quotation for a number
  953. of different parts. You would create a quotation and when you get
  954. confirmation, convert it to a sales order. When you go to ship the item,
  955. you would select the warehouse in the drop-down menu, and select the
  956. parts to ship. One would repeat with other warehouses until the entire
  957. order is shipped.
  958. Then the billing department would go to the sales order and generate
  959. the invoice. It would then be mailed to the customer.
  960. %
  961. \begin{figure}[hbtp]
  962. \caption{Complex AR Workflow with Shipping}
  963. \input{ar_workflow_complex}
  964. \end{figure}
  965. \subsection{Requests for Quotation (RFQ)}
  966. A request for quotation would be a formal document one might submit
  967. to a vendor to ask for a quote on a product or service they might
  968. offer. These can be generated from Purchase Orders or AP Invoices.
  969. \subsection{Purchase Orders}
  970. A purchase order is a confirmation that is issued to the vendor to
  971. order the product or service. Many businesses will require a purchase
  972. order with certain terms in order to begin work on a product. These
  973. can be generated from RFQ's or AP Invoices.
  974. \subsection{Receiving}
  975. The Shipping-\textgreater Receiving screen allows you to track the
  976. parts received from an existing purchase order. Like shipping, it
  977. does not post an invoice but tracks the received parts in the order.
  978. \subsection{AP Work Flow}
  979. \subsubsection{Bookkeeper entering the received items, order completed in full}
  980. Your company inquires about the price of a given good or service from
  981. another firm. You submit an RFQ to the vendor, and finding that the
  982. price is reasonable, you convert it to an order, adjust the price
  983. to what they have quoted, and save it. When the goods are delivered
  984. you convert the order into an AP invoice and post it.
  985. %
  986. \begin{figure}[hbtp]
  987. \caption{Simple AP Workflow}
  988. \input{simple_ap_workflow}
  989. \end{figure}
  990. \subsubsection{Bookkeeper entering received items, order completed in part}
  991. Your company inquires about the price of a given good or service from
  992. another firm, You submit an RFQ to the vendor, and finding that the
  993. price is acceptable, you convert it into an order, adjusting the price
  994. to what they have quoted, and save it. When some of the goods are
  995. received, you open up the purchase order, enter the number of parts
  996. received, convert that order into an invoice, and post it. Repeat
  997. until all parts are received.
  998. %
  999. \begin{figure}[hbtp]
  1000. \caption{AP Workflow with Receiving}
  1001. \input{ap_workflow_ship}
  1002. \end{figure}
  1003. \subsubsection{Receiving staff entering items}
  1004. Your company inquires about the price of a given good or service from
  1005. another firm, You submit an RFQ to the vendor, and finding that the
  1006. price is acceptable, you convert it into an order, adjusting the price
  1007. to what they have quoted, and save it. When some or all of the goods
  1008. are received, the receiving staff goes to Shipping-Receiving, locates
  1009. the purchase order, and fills in the number of items received.
  1010. The bookkeeper can then determine when all items have been received
  1011. and post the invoice at that time.
  1012. %
  1013. \begin{figure}[hbtp]
  1014. \caption{Complex AP Workflow}
  1015. \input{ap_workflow_complex}
  1016. \end{figure}
  1017. \subsection{Generation and Consolidation}
  1018. \subsubsection{Generation}
  1019. The Generation screen allows you to generate Purchase Orders based
  1020. on sales orders. One selects the sales orders one wants to use, and
  1021. clicks \char`\"{}Generate Purchase Orders.\char`\"{} Then one selects
  1022. clicks on the parts to order, adjusts the quantity if necessary, and
  1023. clicks \char`\"{}Select Vendor.\char`\"{} This process is repeated
  1024. for every vendor required. Then the Generate Orders button is clicked.
  1025. \subsubsection{Consolidation}
  1026. One can consolidate sales and/or purchase orders using this screen.
  1027. For the consolidation to work you must have more than one order associated
  1028. with the relevant customer or vendor.
  1029. \subsection{Reporting}
  1030. The reporting functionality in the order management is largely limited
  1031. to the ability to locate purchase orders, sales orders, RFQ's, and
  1032. quotations.
  1033. \subsection{Shipping Module: Transferring Inventory between Warehouses}
  1034. One can transfer inventory between warehouses if necessary by using
  1035. the Shipping-\textgreater Transfer Inventory screen.
  1036. \section{HR}
  1037. The HR module is currently limited to tracking employees for and their
  1038. start and end dates. It has very little other functionality. One could
  1039. build payroll systems that could integrate with it however.
  1040. \section{POS}
  1041. LedgerSMB 1.2 includes a number of components merged from Metatron Technology
  1042. Consulting's SL-POS. Although it is still not a perfect solution, it is greatly improved in both workflow and hardware support. It is suitable for retail
  1043. establishments at the moment.
  1044. \subsection{Sales Screen}
  1045. The sales screen looks very much like a normal invoice entry screen
  1046. with a few differences.
  1047. \begin{itemize}
  1048. \item The discount text field is not available, nor is the unit field..
  1049. \item The next part number is automatically focused when the data loads
  1050. for rapid data entry.
  1051. \item Hot keys for the buttons are Alt-U for update, Alt-P for print, Alt-O
  1052. for post, and Alt-R for print and post.
  1053. \item Part Groups appear at the bottom of the screen.
  1054. \item Alt-N moves the cursor to the next free payment line.
  1055. \end{itemize}
  1056. \subsection{Possibilities for Data Entry}
  1057. \begin{itemize}
  1058. \item Barcode scanners can be used to scan items in as they are being rung
  1059. in.
  1060. \item One could use touch screens, though this would ideally require some
  1061. custom stylesheets to make it efficient.
  1062. \end{itemize}
  1063. \subsection{Hardware Support}
  1064. As LedgerSMB is a web-based application, the web browser usually
  1065. does not allow the page to write to arbitrary files. Therefore hardware
  1066. support for pole displays, etc. is not readily possible from the application
  1067. itself. LedgerSMB gets around this limitation by using an additional set of
  1068. network sockets from the server to the client to control its hardware. This
  1069. naturally requires that other software is also running on the client.
  1070. Notes for specific types of hardware are as follows:
  1071. \begin{description}
  1072. \item [{Touch}] screens: The default stylesheet is not really usable from
  1073. a touchscreen as the items are often too small. One would need to
  1074. modify the stylesheets to ensure that the relevant items would be
  1075. reasonable. Setting down the resolution would also help.
  1076. \item [{Receipt}] Printers: ESC/POS printers generally work in text mode.
  1077. Control sequences can be embedded in the template as necessary.
  1078. \item [{Pole}] Displays: Generally supported. Only the Logic Controls PD3000 is
  1079. supported out of the box, but making this work for other models ought to be
  1080. trivial.
  1081. \item [{Cash}] Drawers: These should be attached to the printer. The control
  1082. codes is then specified in the pos.conf.pl so that the command is sent to the
  1083. printer when the open till button is pushed.
  1084. \item [{Barcode}] Scanners: Most customers use decoded barcode scanners
  1085. through a keyboard wedge interface. This allows them to scan items
  1086. as if they were typing them on the keyboard.
  1087. \end{description}
  1088. \subsection{Reports}
  1089. \subsubsection{Open Invoices}
  1090. The POS-\textgreater Open screen allows one to find any POS receipts
  1091. that are not entirely paid off.
  1092. \subsubsection{Receipts}
  1093. The POS-\textgreater Receipts screen allows one to bring up a basic
  1094. record of the POS terminals. It is not sufficient for closing the
  1095. till, however, though it may help for reconciliation.
  1096. The till column is the last component or octet of the terminal's IP
  1097. address. Therefore it is a good idea to try to avoid having IP addresses
  1098. where the last octet is the same.
  1099. All entries are grouped by date and source in this report.
  1100. \section{General Ledger}
  1101. \subsection{GL Basics}
  1102. The General Ledger is the heart of Ledger-SMB. Indeed, Ledger-SMB
  1103. is designed to be as close as possible to a software equivalent of
  1104. a paper-based accounting program (but with no difference between the
  1105. General Ledger and General Journal).
  1106. \subsubsection{Paper-based accounting systems and the GL}
  1107. In order to understand the principle of the General Ledger, one must
  1108. have a basic understanding of the general process of bookkeeping using
  1109. double-entry paper-based accounting systems.
  1110. Normally when a transaction would be recorded, it would first be recorded
  1111. in the \char`\"{}General Journal\char`\"{} which would contain detailed
  1112. information about the transaction, notes, etc. Then the entries from
  1113. the General Journal would be transcribed to the General Ledger, where
  1114. one could keep closer tabs on what was going on in each account.
  1115. In the general journal, all transactions are listed chronologically
  1116. with whatever commentary is deemed necessary, while in the general
  1117. ledger each account has its own page and transactions are recorded
  1118. in a simple and terse manner. The General Journal is the first place
  1119. the transaction is recorded and the General Ledger is the last.
  1120. At the end of the accounting period, the GL transactions would be
  1121. summarized into a trial balance and this would be used for creating
  1122. financial statements and closing the books at the end of the year.
  1123. \subsubsection{Double Entry Examples on Paper}
  1124. Let us say that John starts his business with an initial investment
  1125. of \$10,000.
  1126. This is recorded in the General Journal as follows (in this example,
  1127. suppose it is page 1):
  1128. \begin{tabular}{|l|l|l|r|r|}
  1129. \hline
  1130. Date &
  1131. Accounts and Explanation &
  1132. Ref &
  1133. DEBIT &
  1134. CREDIT \tabularnewline
  1135. \hline
  1136. March 1 &
  1137. Checking Account &
  1138. 1060 &
  1139. 10000.00 &
  1140. \tabularnewline
  1141. &
  1142. John Doe Capital &
  1143. 3011 &
  1144. &
  1145. 10000.00\tabularnewline
  1146. &
  1147. John Doe began a business &
  1148. &
  1149. &
  1150. \tabularnewline
  1151. &
  1152. with an investment of &
  1153. &
  1154. &
  1155. \tabularnewline
  1156. &
  1157. \$10000 &
  1158. &
  1159. &
  1160. \tabularnewline
  1161. \hline
  1162. \end{tabular}\medskip{}
  1163. This would then be transcribed into two pages of the General Ledger.
  1164. The first page might be the Checking Account page:\medskip{}
  1165. \begin{tabular}{|l|l|l|r|l|l|l|r|}
  1166. \hline
  1167. DATE &
  1168. EXPLANATION &
  1169. REF. &
  1170. DEBITS &
  1171. DATE &
  1172. EXPLANATION &
  1173. REF. &
  1174. CREDITS\tabularnewline
  1175. \hline
  1176. March 1 &
  1177. &
  1178. J1 &
  1179. 10000.00 &
  1180. &
  1181. &
  1182. &
  1183. \tabularnewline
  1184. \hline
  1185. \end{tabular}\medskip{}
  1186. On the John Doe Capital page, we would add a similar entry:\medskip{}
  1187. \begin{tabular}{|l|l|l|r|l|l|l|r|}
  1188. \hline
  1189. DATE &
  1190. EXPLANATION &
  1191. REF. &
  1192. DEBITS &
  1193. DATE &
  1194. EXPLANATION &
  1195. REF. &
  1196. CREDITS\tabularnewline
  1197. \hline
  1198. &
  1199. &
  1200. &
  1201. &
  1202. March 1 &
  1203. &
  1204. J1 &
  1205. 10000.00\tabularnewline
  1206. \hline
  1207. \end{tabular}\medskip{}
  1208. \subsubsection{The GL in Ledger-SMB}
  1209. The paper-based accounting procedure works well when one is stuck
  1210. with paper recording requirements but it has one serious deficiency---
  1211. all of this transcribing creates an opportunity for errors.
  1212. Relational databases relieve the need for such transcription as it
  1213. is possible to store everything physically in a way similar to the
  1214. way a General Journal is used in the paper-based systems and then
  1215. present the same information in ways which are more closely related
  1216. to the General Ledger book.
  1217. This is the exact way that the General Ledger is used in Ledger-SMB.
  1218. The actual data is entered and stored as if it was a general journal,
  1219. and then the data can be presented in any number of different ways.
  1220. All modules of Ledger-SMB that involve COA accounts store their data
  1221. in the General Ledger (it is a little more complex than this but this
  1222. is very close to the actual mechanism).
  1223. \subsection{Cash Transfer}
  1224. The simplest form of GL entry in Ledger-SMB is the Cash-\textgreater
  1225. Transfer screen. This screen shows two transaction lines, and fields
  1226. for reference, department, description, and notes.
  1227. The field descriptions are as follows:
  1228. \begin{description}
  1229. \item [{Reference}] refers to the source document for the transfer. One
  1230. can use transfer sheets, bank receipt numbers, etc for this field.
  1231. \item [{Description}] is optional but really should be filled in. It ought
  1232. to be a description of the transaction.
  1233. \item [{Notes}] provide supplemental information for the transaction.
  1234. \item [{FX}] indicates whether foreign exchange is a factor in this transaction.
  1235. \item [{Debit}] indicates money going \textbf{into} the asset account.
  1236. \item [{Credit}] indicates money coming \textbf{out} of the asset account.
  1237. \item [{Source}] is the source document for that portion of the transaction.
  1238. \item [{Memo}] lists additional information as necessary.
  1239. \item [{Project}] allows you to assign this line to a project.
  1240. \end{description}
  1241. The credit and debit options seem to be the opposite of what one would
  1242. think of concerning one's bank account. The reason is that your bank
  1243. statement is done from the bank's point of view. Your bank account balance
  1244. is an asset to you and therefor you show it as having a debit balance, but
  1245. to the bank it is money they owe you and so they show it as having a credit
  1246. balance.
  1247. Note that in this screen, when an item is updated, it will reduce
  1248. the number of lines to those already filled in plus an extra line
  1249. for the new line in the data entry.
  1250. \subsection{GL Transactions}
  1251. The GL Transaction screen (General Ledger-\textgreater Add Transaction)
  1252. is identical to the Cash Transfer screen with the exception that it
  1253. starts with nine lines instead of two. Otherwise, they are identical.
  1254. Again, one must be careful with debits and credits. Often it is easy
  1255. to get confused. It is generally worth while to go back to the principle
  1256. that one tracks them with regard to their impact on the equity accounts.
  1257. So expenses are credits because they debit the equity accounts, and
  1258. income is a debit because it credits the retained earning equity account.
  1259. \subsection{Payroll as a GL transaction}
  1260. Currently payroll must be done as a GL transaction. The attempts to
  1261. create a payroll system that would ship with LSMB have largely stalled.
  1262. Most customers running their businesses will have an idea of how to
  1263. do this.
  1264. %
  1265. \begin{figure}[hbtp]
  1266. \caption{Payroll as a GL Transaction (Purely fictitious numbers)}
  1267. \begin{tabular}{|l|r|r|}
  1268. \hline
  1269. Account &
  1270. Debit &
  1271. Credit \tabularnewline
  1272. 5101 Wages and Salaries &
  1273. 500 &
  1274. \tabularnewline
  1275. 2032 Accrued Wages &
  1276. &
  1277. 450 \tabularnewline
  1278. 2033 Fed. Income Tax wthd &
  1279. &
  1280. 30 \tabularnewline
  1281. 2034 State Inc. Tax. wthd &
  1282. &
  1283. 15 \tabularnewline
  1284. 2035 Social Security wthd &
  1285. &
  1286. 3 \tabularnewline
  1287. 2036 Medicare wthd &
  1288. &
  1289. 2 \tabularnewline
  1290. 2032 Accrued Wages &
  1291. 450 &
  1292. \tabularnewline
  1293. 1060 Checking Acct &
  1294. &
  1295. 450 \tabularnewline
  1296. \hline
  1297. \end{tabular}
  1298. \end{figure}
  1299. \subsection{Reconciliation}
  1300. To reconcile an account (say, when one would get a checking account
  1301. statement), one would go to cash/reconciliation, and check off the
  1302. items that have cleared. One can then attempt to determine where any
  1303. errors lie by comparing the total on the statement with the total
  1304. that LSMB generates.
  1305. This can be done for other accounts too, such as petty cash.%
  1306. \footnote{Petty cash denotes a drawer of cash that is used to pay small expenses.
  1307. When an expense is paid, it is recorded on a slip of paper that is
  1308. stored for reconciliation purposes.%
  1309. }
  1310. \subsection{Reports}
  1311. The most flexible report in Ledger-SMB is the GL report because it
  1312. has access to the entire set of financial transactions of a business.
  1313. Every invoice posted, payment made or received, etc. can be located
  1314. here.
  1315. The search criteria include:
  1316. \begin{description}
  1317. \item [{Reference}] is the invoice number, or other reference number associated
  1318. with the transaction.
  1319. \item [{Source}] is the field related to the source document number in
  1320. a payment or other transaction.%
  1321. \footnote{Source documents are things like receipts, canceled checks, etc. that
  1322. can be used to verify the existence and nature of a transaction.%
  1323. }
  1324. \item [{Memo}] relates to the memo field on a payment.
  1325. \item [{Department}] can be used to filter results by department.
  1326. \item [{Account}] Type can be used to filter results by type of account
  1327. (Asset, Liability, etc.)
  1328. \item [{Description}] can be used to filter by GL description or by
  1329. customer/vendor name.
  1330. \end{description}
  1331. The actual format of the report looks more like what one would expect
  1332. in a paper accounting system's general journal than a general ledger
  1333. per se. A presentation of the data that is more like the paper general
  1334. ledger is found in the Chart of Accounts report.
  1335. \subsubsection{GL as access to almost everything else}
  1336. The GL reports can be used to do all manner of things. One can determine,
  1337. for example, which AP invoice or transaction was paid with a certain
  1338. check number or which invoice by a specific customer was paid by a specific
  1339. check number.
  1340. \subsection{Using GL entries for Depreciation}
  1341. GL entries can also be used for entering depreciation expenses at year end.
  1342. There are several different methods for entering depreciation and, if in
  1343. doubt, please contact an accountant for advice. Methods include:
  1344. \begin{itemize}
  1345. \item The Straight-Line Method (an equal portion of the asset is depreciated
  1346. each year).
  1347. \item The Units of Production Method (an equal portion of the asset is
  1348. depreciated for each unit produced with the equipment--- this is usually used
  1349. in manufacturing businesses).
  1350. \item Declining Balance Method
  1351. \item Sum-of-the-Years'-Digits Method
  1352. \end{itemize}
  1353. \section{Recurring Transactions}
  1354. Any transaction or invoice may be repeated a number of times in regular
  1355. intervals. To schedule any GL, AR, or AP transaction or invoice, click
  1356. the schedule button.
  1357. In general the reference number should be left blank as this will
  1358. force Ledger-SMB to create a new invoice or transaction number for
  1359. each iteration. The rest of the options are self-explanatory. Note
  1360. that a blank number if iterations will result in no recurrences of
  1361. the transaction.
  1362. To process the recurring transactions, click on the Recurring Transactions
  1363. option on the main menu select the ones you want to process and click
  1364. \char`\"{}Process Transactions.\char`\"{}
  1365. \section{Financial Statements and Reports}
  1366. Financial statements and reports are a very important part of any
  1367. accounting system. Accountants and business people rely on these reports
  1368. to determine the financial soundness of the business and its prospects
  1369. for the next accounting period.
  1370. \subsection{Cash v. Accrual Basis}
  1371. Financial statements, such as the Income Statement and Balance Sheet
  1372. can be prepared either on a cash or accrual basis. In cash-basis accounting,
  1373. the income is deemed earned when the customer pays it, and the expenses
  1374. are deemed incurred when the business pays them.
  1375. There are a number of problems with cash-basis accounting from a business
  1376. point of view. The most serious is that one can misrepresent the wellbeing
  1377. of a business by paying a large expense after a deadline. Thus cash-basis
  1378. accounting does not allow one to accurately pair the income with the
  1379. related expense as these are recorded at different times. If one cannot
  1380. accurately pair the income with the related expense, then financial
  1381. statements cannot be guaranteed to tell one much of anything about
  1382. the well-being of the business.
  1383. In accrual basis accounting, income is considered earned when the
  1384. invoice is posted, and expenses are considered incurred at the time
  1385. when the goods or services are delivered to the business. This way,
  1386. one can pair the income made from the sale of a product with the expense
  1387. incurred in bringing that product to sale. This pairing allows for
  1388. greater confidence in business reporting.
  1389. \subsection{Viewing the Chart of Accounts and Transactions}
  1390. The Reports--\textgreater Chart of Accounts will provide the chart
  1391. of accounts along with current totals in each account.
  1392. If you click on an account number, you will get a screen that allows
  1393. you to filter out transactions in that account by various criteria.
  1394. One can also include AR/AP, and Subtotal in the report.
  1395. The report format is similar to that of a paper-based general ledger.
  1396. \subsection{Trial Balance}
  1397. \subsubsection{The Paper-based function of a Trial Balance}
  1398. In paper-based accounting systems, the accountant at the end of the
  1399. year would total up the debits and credits in every account and transfer
  1400. them onto another sheet called the trial balance. The accountant would
  1401. check to determine that the total debits and credits were equal and
  1402. would then transfer this information onto the financial statements.
  1403. It was called a trial balance because it was the main step at which
  1404. the error-detection capabilities of double-entry accounting systems
  1405. were used.
  1406. \subsubsection{Running the Trial Balance Report}
  1407. This report is located under Reports --\textgreater Trial Balance.
  1408. One can filter out items by date, accounting period, or department.
  1409. One can run the report by accounts or using GIFI classifications to
  1410. group accounts together.
  1411. From this report, you can click on the account number and see all
  1412. transactions on the trial balance as well as whether or not they have
  1413. been reconciled.
  1414. \subsubsection{What if the Trial Balance doesn't Balance?}
  1415. If the trial balance does not balance, get technical support immediately.
  1416. This usually means that transactions were not entered properly. Some
  1417. may have been out of balance, or some may have gone into non-existent
  1418. accounts (believe it or not, Ledger-SMB does not check this latter
  1419. issue).
  1420. \subsubsection{Trial Balance as a Summary of Account Activity}
  1421. The trial balance offers a glance at the total activity in every account.
  1422. It can provide a useful look at financial activity at a glance for
  1423. the entire business.
  1424. \subsubsection{Trial Balance as a Budget Planning Tool}
  1425. By filtering out departments, one can determine what a department
  1426. earned and spent during a given financial interval. This can be used
  1427. in preparing budgets for the next accounting period.
  1428. \subsection{Income Statement}
  1429. The Income Statement is another tool that can be used to assist with
  1430. budgetary planning as well as provide information on the financial
  1431. health of a business.
  1432. The report is run from Reports--\textgreater Income Statement. The
  1433. report preparation screen shows the following fields:
  1434. \begin{description}
  1435. \item [{Department}] allows you to run reports for individual departments.
  1436. This is useful for budgetary purposes.
  1437. \item [{Project}] allows you to run reports on individual projects. This
  1438. can show how profitable a given project was during a given time period.
  1439. \item [{From}] and To allow you to select arbitrary from and to dates.
  1440. \item [{Period}] allows you to specify a standard accounting period.
  1441. \item [{Compare to}] fields allow you to run a second report for comparison
  1442. purposes for a separate range of dates or accounting period.
  1443. \item [{Decimalplaces}] allows you to display numbers to a given precision.
  1444. \item [{Method}] allows you to select between accrual and cash basis reports.
  1445. \item [{Include}] in Report provides various options for reporting.
  1446. \item [{Accounts}] allows you to run GIFI reports instead of the standard
  1447. ones.
  1448. \end{description}
  1449. The report shows all income and expense accounts with activity during
  1450. the period when the report is run, the balances accrued during the
  1451. period, as well as the total income and expense at the bottom of each
  1452. section. The total expense is subtracted from the total income to
  1453. provide the net income during the period. If there is a loss, it appears
  1454. in parentheses.
  1455. \subsubsection{Uses of an Income Statement}
  1456. The income statement provides a basic snapshot of the overall ability
  1457. of the business to make money. It is one of the basic accounting statements
  1458. and is required, for example, on many SEC forms for publicly traded
  1459. firms.
  1460. Additionally, businessmen use the income statement to look at overall
  1461. trends in the ability of the business to make money. One can compare
  1462. a given month, quarter, or year with a year prior to look for trends
  1463. so that one can make adjustments in order to maximize profit.
  1464. Finally, these reports can be used to provide a look at each department's
  1465. performance and their ability to work within their budget. One can
  1466. compare a department or project's performance to a year prior and
  1467. look for patterns that can indicate problems or opportunities that
  1468. need to be addressed.
  1469. \subsection{Balance Sheet}
  1470. The balance sheet is the second major accounting statement supported
  1471. by Ledger-SMB. The balance sheet provides a snapshot of the current
  1472. financial health of the business by comparing assets, liabilities,
  1473. and equity.
  1474. In essence the balance sheet is a statement of the current state of
  1475. owner equity. Traditionally, it does not track changes in owner equity
  1476. in the same way the Statement of Owner Equity does.
  1477. The Balance Sheet report preparation screen is much simpler than the
  1478. Income Statement screen. Balance sheets don't apply to projects, but
  1479. they do apply to departments. Also, unlike an income statement, a
  1480. balance sheet is fixed for a specific date in time. Therefore one
  1481. does not need to select a period.
  1482. The fields in creating a balance sheet are:
  1483. \begin{description}
  1484. \item [{Department}] allows you to run separate balance sheets for each
  1485. department.
  1486. \item [{As}] at specifies the date. If blank this will be the current date.
  1487. \item [{Compare to}] specifies the date to compare the balance sheet to.
  1488. \item [{Decimalplaces}] specifies the number of decimal places to use.
  1489. \item [{Method}] selects between cash and accrual basis.
  1490. \item [{Include}] in report allows you to select supplemental information
  1491. on the report.
  1492. \item [{Accounts}] allows you to select between standard and GIFI reports.
  1493. \end{description}
  1494. The balance sheet lists all asset, liability, and equity accounts
  1495. with a balance. Each category has a total listed, and the total of
  1496. the equity and liability accounts is also listed.
  1497. The total assets should be equal to the sum of the totals of the liability
  1498. and equity accounts.
  1499. \subsection{What if the Balance Sheet doesn't balance?}
  1500. Get technical support immediately, This may indicate that out of balance
  1501. transactions were entered or that transactions did not post properly.
  1502. \subsection{No Statement of Owner Equity?}
  1503. The Statement of Owner Equity is the one accounting statement that
  1504. Ledger-SMB does not support. However, it can be simulated by running
  1505. a balance sheet at the end of the time frame in question and comparing
  1506. it to the beginning. One can check this against an income statement
  1507. for the period in question to verify its accuracy. The statement of
  1508. owner equity is not as commonly used now as it once was.
  1509. \section{The Template System}
  1510. Ledger-SMB allows most documents to be generated according to a template
  1511. system. This allows financial statements, invoices, orders, and the
  1512. like to be customized to meet the needs of most businesses. Company
  1513. logos can be inserted, the format can be radically altered, one can
  1514. print letters to be included with checks to vendors instead of the
  1515. checks themselves, and the like. In the end, there is very little
  1516. that cannot be accomplished regarding modification of these documents
  1517. with the template system.
  1518. One can define different templates for different languages, so that
  1519. a customer in Spain gets a different invoice than a customer in Canada.
  1520. \subsection{Text Templates}
  1521. The only template that uses a text-only format is the POS receipt.
  1522. This example provides the simplest way to understand the template
  1523. system.
  1524. The first two lines are:\\
  1525. \textless\%company align=center width=40\%\textgreater\\
  1526. \textless\%address align=center width=40\%\textgreater\\
  1527. The first line tells Ledger-SMB to print the company name as passed
  1528. to it via a variable, centered, with a page width of 40 characters.
  1529. The second line does the same thing with the address.
  1530. These variables are usually passed to the invoice using form fields
  1531. (hidden or otherwise) in the submitting web page. The printing script,
  1532. however, can disable some of these fields or add others via database
  1533. lookups and the like.
  1534. In all types of templates, variable substitution occurs between \textless\%
  1535. and \%\textgreater. One can optionally specify an alignment or a
  1536. width but these are really only useful in text templates.
  1537. \subsection{HTML Templates}
  1538. The following templates exist in HTML format:
  1539. \begin{itemize}
  1540. \item Income Statement
  1541. \item Balance Sheet
  1542. \item Invoice (AR)
  1543. \item AR Transaction
  1544. \item AP Transaction
  1545. \item Packing List
  1546. \item Pick List
  1547. \item Sales Order
  1548. \item Work Order
  1549. \item Purchase Order
  1550. \item Bin List
  1551. \item Statement
  1552. \item Quotation
  1553. \item RFQ
  1554. \item Time Card
  1555. \end{itemize}
  1556. These templates can be edited by an HTML editor. However, it is generally
  1557. recommended that one back up templates first. The reason is that some
  1558. HTML editors will fully re-parse the HTML and save it back without
  1559. what they see as invalid tags. Most editors, however, will save the
  1560. variable substitution tags because similar tags are also used by Microsoft's
  1561. active server pages.
  1562. Finally, some editors are known to mangle formatting, so many problems
  1563. can be avoided by ensuring that one has a backup of the templates,
  1564. especially if they have already been customized.
  1565. \subsection{\LaTeX{}\ Templates}
  1566. The following templates, by default, are available in \LaTeX{}\ :
  1567. \begin{itemize}
  1568. \item Invoice
  1569. \item AR Transaction
  1570. \item AP Transaction
  1571. \item Packing List
  1572. \item Pick List
  1573. \item Sales Order
  1574. \item Work Order
  1575. \item Purchase Order
  1576. \item Bin List
  1577. \item Statement
  1578. \item Check
  1579. \item Receipt
  1580. \item Quotation
  1581. \item RFQ
  1582. \item Time Card
  1583. \end{itemize}
  1584. \LaTeX{}\ templates allow one to generate PDF and postscript documents
  1585. and print directly to a postscript-enabled printer or print software
  1586. (like CUPS).
  1587. \LaTeX{}\ templates can be edited using a standard text editor (like
  1588. vim or emacs), or using a synchronous \LaTeX{}\ implementation such
  1589. as \LyX{}.
  1590. \subsubsection{What is \LaTeX{}\ ?}
  1591. \LaTeX{}\ (pronounced LAY-tech) is an extension on the \TeX{}\ typesetting
  1592. system. It largely consists of a set of macros that allow one to focus
  1593. on the structure of the document while letting the \TeX{}\ engine
  1594. do the heavy lifting in terms of determining the optimal formatting
  1595. for the page. \LaTeX{}\ is used in a large number of academic journals
  1596. (including those of the American Mathematics Association). It is available
  1597. at \url{http://www.tug.org} and is included in most Linux distributions.
  1598. Like HTML, \LaTeX{}\ uses plain text documents to store the formatting
  1599. information and then when the document is rendered, attempts to fit
  1600. it onto a page. \LaTeX{}\
  1601. supports the concept of stylesheets, allowing one to separate content
  1602. from format, and this feature is used in many higher-end applications,
  1603. like journal publication.
  1604. Unlike HTML, \LaTeX{}\ is a complete though simple programming language
  1605. that allows one to redefine internals of the system for formatting
  1606. purposes.
  1607. This document is written in \LaTeX{}.
  1608. \subsubsection{Using \LyX{} to Edit \LaTeX{}\ Templates}
  1609. \LyX{} is a synchronous \LaTeX{}\ editor that runs on Windows, UNIX/Linux,
  1610. and Mac OS X. It requires an installed \LaTeX{}-2e implementation
  1611. and can be obtained at \url{http://www.lyx.org}. Like the most common
  1612. \LaTeX{}\ implementations, it is open source and is included with most
  1613. Linux distributions.
  1614. \subsection{Customizing Logos}
  1615. \LaTeX{}\ requires different formats of logos depending on whether
  1616. the document is going to be generated as a PDF or as postscript. Postscript
  1617. requires an embedded postscript graphic, while PDF requires any type
  1618. of graphic other than embedded postscript. Usually one uses a PNG's
  1619. for PDF's, though GIF's could be used as well. The logo for a \LaTeX{}\ document
  1620. resides in the users directory.
  1621. HTML documents can have logos in many different formats. PNG's are
  1622. generally preferred for printing reasons. The image can be stored
  1623. anywhere and merely referenced in the HTML.
  1624. Note: Always test the an invoice with images to ensure that
  1625. the rest of the page format is not thrown off by it.
  1626. \subsection{How are They Stored in the Filesystem?}
  1627. The template directory (\char`\"{}templates\char`\"{} in the root
  1628. Ledger-SMB install directory) contains all the root templates used
  1629. by Ledger-SMB. These follow a naming convention of COAType-templatename.ext
  1630. where COAType is the type of dataset that was created when the user
  1631. was created, templatename is the name of the template, and ext is
  1632. either txt, html, or tex (for text, html, and \LaTeX{}\ respectively).
  1633. Inside this directory are one or more subdirectories where the relevant
  1634. templates have been copied as default language templates for the user.
  1635. Many users can use the same user directory (which bears the name of
  1636. the Ledger-SMB username). Within this directory are more subdirectories
  1637. for translated templates, one for each language created.
  1638. \subsection{Upgrade Issues}
  1639. When Ledger-SMB is upgraded, the templates are not replaced. This
  1640. is designed to prevent the upgrade script from overwriting changes
  1641. made during the course of customizing the templates.
  1642. Occasionally, however, the data model changes in a way which can cause
  1643. the templates to stop printing certain information. When information
  1644. that was showing up before an upgrade stops showing up, one can either
  1645. upgrade the templates by copying the source template over the existing
  1646. one, or one can edit the template to make the change.
  1647. \section{An Introduction to the CLI}
  1648. \subsection{Conventions}
  1649. The command-line API will be referred to as the API.
  1650. \subsection{Preliminaries}
  1651. Logging into Ledger-SMB (1.2+) updates a row in the users\_conf table
  1652. containing your account configuration defaults and other information.
  1653. The implication for API users of LSMB is that you must login as part
  1654. of running API scripts. For security purposes, it is recommended that
  1655. scripts prompt for a password rather than storing it.
  1656. All scripts included in the documentation can also be found in the doc/samples
  1657. directory.
  1658. Consider a simple example:
  1659. cd /usr/local/ledger-smb
  1660. ./ct.pl "login=name\&path=bin\&password=xxxxx\&action=search\&db=customer"
  1661. The cd command moves your terminal session's current working directory into
  1662. the main Ledger-SMB directory. Then the Ledger-SMB perl script ct.pl is called
  1663. with one long line as an argument. The argument is really several variable=value pairs
  1664. separated by ampersands (\&). The value for the login variable is the username
  1665. that Ledger-SMB is to use, and the value for the password variable is the plaintext password.
  1666. To build our examples we will use a username of "clarkkent" who has a password
  1667. of "lOis,lAn3".
  1668. cd /usr/local/ledger-smb
  1669. ./ct.pl "login=clarkkent\&path=bin\&password=lOis,lAn3\&action=search\&db=customer"
  1670. If we execute these commands we will get the html for the search form for
  1671. the customer database. This result isn't useful in itself, but it shows we
  1672. are on the right track.
  1673. \subsection{First Script: lsmb01-cli-example.sh}
  1674. With a working example, we can start to build reproducible routines that we can grow
  1675. to do some useful work.
  1676. This is a bash script which:
  1677. 1. sets NOW to the current working directory
  1678. 2. prompts for and reads your Ledger-SMB login
  1679. 3. prompts for and reads (non-echoing) your Ledger-SMB password
  1680. 4. changes directory to /usr/local/ledger-smb
  1681. 5. constructs login and logout commands and a transaction command
  1682. 6. logins into ledger-smb (in a real program, output would be checked for
  1683. success or failure)
  1684. 7. executes the transaction
  1685. 8. logs out of ledger-smb (although this is not necessary)
  1686. 9. returns to the original working directory
  1687. 10. exits
  1688. Running lsmb01-cli-example.sh produces:
  1689. \$ lsmb01-cli-example.sh
  1690. Ledger-SMB login: clarkkent
  1691. Ledger-SMB password:
  1692. \begin{verbatim}
  1693. <body>
  1694. <form method=post action=ct.pl>
  1695. <input type=hidden name=db value=customer>
  1696. <table width=100%>
  1697. <tr>
  1698. <th class=listtop>Search</th>
  1699. .
  1700. .
  1701. .
  1702. \end{verbatim}
  1703. A script like this would work well for simple batch transactions, but
  1704. bash is not a very friendly language for application programming.
  1705. A nicer solution would be to use a language such as perl to drive the
  1706. command line API.
  1707. \subsubsection{Script 1 (Bash)}
  1708. \begin{verbatim}
  1709. #!/bin/bash
  1710. #######################################################################
  1711. #
  1712. # lsmb01-cli-example.sh
  1713. # Copyright (C) 2006. Louis B. Moore
  1714. #
  1715. # $Id: $
  1716. #
  1717. # This program is free software; you can redistribute it and/or modify
  1718. # it under the terms of the GNU General Public License as published by
  1719. # the Free Software Foundation; either version 2 of the License, or
  1720. # (at your option) any later version.
  1721. #
  1722. # This program is distributed in the hope that it will be useful,
  1723. # but WITHOUT ANY WARRANTY; without even the implied warranty of
  1724. # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  1725. # GNU General Public License for more details.
  1726. # You should have received a copy of the GNU General Public License
  1727. # along with this program; if not, write to the Free Software
  1728. # Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  1729. #
  1730. #######################################################################
  1731. NOW=`pwd`
  1732. echo -n "Ledger-SMB login: "
  1733. read LSLOGIN
  1734. echo
  1735. echo -n "Ledger-SMB password: "
  1736. stty -echo
  1737. read LSPWD
  1738. stty echo
  1739. echo
  1740. ARG="login=${LSLOGIN}&password=${LSPWD}&path=bin&action=search&db=customer"
  1741. LGIN="login=${LSLOGIN}&password=${LSPWD}&path=bin&action=login"
  1742. LGOT="login=${LSLOGIN}&password=${LSPWD}&path=bin&action=logout"
  1743. cd /usr/local/ledger-smb
  1744. ./login.pl $LGIN 2>&1 > /dev/null
  1745. ./ct.pl $ARG
  1746. ./login.pl $LGOT 2>&1 > /dev/null
  1747. cd $NOW
  1748. exit 0
  1749. \end{verbatim}
  1750. \subsection{Second Script: lsmb02-cli-example.pl}
  1751. Our second script is written in perl and logs you in but it still uses the API
  1752. in its simplest form, that is, it builds commands and then executes them. This
  1753. type of script can be used for more complex solutions than the simple bash script
  1754. above, though it is still fairly limited. If your needs require, rather than have
  1755. the script build and then execute the commands it could be written to generate a
  1756. shell script which is executed by hand.
  1757. This script begins by prompting for your Ledger-SMB login and password. Using
  1758. the supplied values a login command is constructed and passed into the runLScmd
  1759. subroutine. runLScmd changes directory to /usr/local/ledger-smb/ for the length
  1760. of the subroutine. It formats the command and executes it and returns both the
  1761. output and error information to the caller in a scalar.
  1762. The script checks to see if there was an error in the login, exiting if there was.
  1763. Next, the script reads some records which are stored in the program following the
  1764. \_\_END\_\_ token. It takes each record in turn, formats it then feeds each transaction
  1765. through runLScmd and looks at the results for a string that signals success.
  1766. Once all the transactions are processed, runLScmd is called one last time to
  1767. logout and the script exits.
  1768. \subsubsection{Script 2 (Perl)}
  1769. \begin{verbatim}
  1770. #!/usr/bin/perl -w
  1771. #
  1772. # File: lsmb02-cli-example.pl
  1773. # Environment: Ledger-SMB 1.2.0+
  1774. # Author: Louis B. Moore
  1775. #
  1776. # Copyright (C) 2006 Louis B. Moore
  1777. #
  1778. # This program is free software; you can redistribute it and/or
  1779. # modify it under the terms of the GNU General Public License
  1780. # as published by the Free Software Foundation; either version 2
  1781. # of the License, or (at your option) any later version.
  1782. #
  1783. # This program is distributed in the hope that it will be useful,
  1784. # but WITHOUT ANY WARRANTY; without even the implied warranty of
  1785. # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  1786. # GNU General Public License for more details.
  1787. #
  1788. # You should have received a copy of the GNU General Public License
  1789. # along with this program; if not, write to the Free Software
  1790. # Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  1791. #
  1792. # Revision:
  1793. # $Id$
  1794. #
  1795. #
  1796. use File::chdir;
  1797. use HTML::Entities;
  1798. print "\n\nLedger-SMB login: ";
  1799. my $login = <STDIN>;
  1800. chomp($login);
  1801. print "\nLedger-SMB password: ";
  1802. system("stty -echo");
  1803. my $pwd = <STDIN>;
  1804. system("stty echo");
  1805. chomp($pwd);
  1806. print "\n\n";
  1807. $cmd = "login=" . $login . '&password=' . $pwd . '&path=bin&action=login';
  1808. $signin = runLScmd("./login.pl",$cmd);
  1809. if ( $signin =~ m/Error:/ ) {
  1810. print "\nLogin error\n";
  1811. exit;
  1812. }
  1813. while (<main::DATA>) {
  1814. chomp;
  1815. @rec = split(/\|/);
  1816. $arg = 'path=bin/mozilla&login=' . $login . '&password=' . $pwd .
  1817. '&action=' . escape(substr($rec[0],0,35)) .
  1818. '&db=' . $rec[1] .
  1819. '&name=' . escape(substr($rec[2],0,35)) .
  1820. '&vendornumber=' . $rec[3] .
  1821. '&address1=' . escape(substr($rec[4],0,35)) .
  1822. '&address2=' . escape(substr($rec[5],0,35)) .
  1823. '&city=' . escape(substr($rec[6],0,35)) .
  1824. '&state=' . escape(substr($rec[7],0,35)) .
  1825. '&zipcode=' . escape(substr($rec[8],0,35)) .
  1826. '&country=' . escape(substr($rec[9],0,35)) .
  1827. '&phone=' . escape(substr($rec[10],0,20)) .
  1828. '&tax_2150=1' .
  1829. '&taxaccounts=2150' .
  1830. '&taxincluded=0' .
  1831. '&terms=0';
  1832. $rc=runLScmd("./ct.pl",$arg);
  1833. if ($rc =~ m/Vendor saved!/) {
  1834. print "$rec[2] SAVED\n";
  1835. } else {
  1836. print "$rec[2] ERROR\n";
  1837. }
  1838. }
  1839. $cmd = "login=" . $login . '&password=' . $pwd . '&path=bin&action=logout';
  1840. $signin = runLScmd("./login.pl",$cmd);
  1841. if ( $signin =~ m/Error:/ ) {
  1842. print "\nLogout error\n";
  1843. }
  1844. exit;
  1845. #*******************************************************
  1846. # Subroutines
  1847. #*******************************************************
  1848. sub runLScmd {
  1849. my $cmd = shift;
  1850. my $args = shift;
  1851. my $i = 0;
  1852. my $results;
  1853. local $CWD = "/usr/local/ledger-smb/";
  1854. $cmd = $cmd . " \"" . $args . "\"";
  1855. $results = `$cmd 2>&1`;
  1856. return $results;
  1857. }
  1858. sub escape {
  1859. my $str = shift;
  1860. if ($str) {
  1861. decode_entities($str);
  1862. $str =~ s/([^a-zA-Z0-9_.-])/sprintf("%%%02x", ord($1))/ge;
  1863. }
  1864. return $str;
  1865. }
  1866. #*******************************************************
  1867. # Record Format
  1868. #*******************************************************
  1869. #
  1870. # action | db | name | vendornumber | address1 | address2 | city | state | zipcode | country | phone
  1871. #
  1872. __END__
  1873. save|vendor|Parts are Us|1377|238 Riverview|Suite 11|Cheese Head|WI|56743|USA|555-123-3322|
  1874. save|vendor|Widget Heaven|1378|41 S. Riparian Way||Show Me|MO|39793|USA|555-231-3309|
  1875. save|vendor|Consolidated Spackle|1379|1010 Binary Lane|Dept 1101|Beverly Hills|CA|90210|USA|555-330-7639 x772|
  1876. \end{verbatim}
  1877. \clearpage
  1878. \part{Technical Overview}
  1879. \section{Basic Architecture}
  1880. Ledger-SMB is a web-based Perl program that interfaces with PostgreSQL
  1881. using the relevant Perl modules. The code is well partitioned, and
  1882. the main operation modules are written in an object oriented way.
  1883. \subsection{The Software Stack}
  1884. %
  1885. \begin{figure}[hbtp]
  1886. \label{fig-sl-stack} \input{sl-stack.tex}
  1887. \caption{The Ledger-SMB software stack in a Typical Implementation}
  1888. \end{figure}
  1889. Ledger-SMB runs in a Perl interpreter. I do not currently know if
  1890. it is possible to run it with Perl2C or other language converters
  1891. to run in other environments. However, except for high-capacity environments,
  1892. Perl is a good language choice for this sort of program.
  1893. Ledger-SMB used to support DB2 and Oracle as well as PostgreSQL. However,
  1894. currently some of the functionality is implemented using PostgreSQL
  1895. user-defined functions. These would need to be ported to other database
  1896. managers in order to make the software work on these. It should not
  1897. be too hard, but the fact that it has not been done yet may mean that
  1898. there is no real demand for running the software under other RDBMS's.
  1899. One can substitute other web servers for Apache. Normally Ledger-SMB
  1900. is run as a CGI program but it may be possible to run it in the web
  1901. server process (note that this may not be entirely thread-safe).
  1902. The operating system can be any that supports a web server and Perl
  1903. (since PostgreSQL need not run on the same system). However, there
  1904. are a few issues running Ledger-SMB on Windows (most notably in trying
  1905. to get Postscript documents to print properly).
  1906. On the client side, any web-browser will work. Currently, the layout
  1907. is different for Lynx (which doesn't support frames), and the layout
  1908. is not really useful under eLinks (the replacement for Lynx which
  1909. does support frames). Some functionality requires Javascript to work
  1910. properly, though the application is usable without these features.
  1911. \subsection{Capacity Planning}
  1912. Some companies may ask how scalable Ledger-SMB is. In general, it
  1913. is assumed that few companies are going to have a need for a high-concurrency
  1914. accounting system. However, with all the features available in Ledger-SMB,
  1915. the staff that may have access to some of the application may be senior
  1916. enough to make the question worthwhile.
  1917. This question also becomes more important when companies might look
  1918. at integrating Ledger-SMB with a CRM solution, online store, or other
  1919. environment. This section looks at a number of the known issues and
  1920. their solutions.
  1921. \subsubsection{Scalability Strategies}
  1922. Ledger-SMB is a fairly standard web-based application. However,
  1923. sometimes the database schema changes during upgrades. In these cases,
  1924. it becomes impossible to use different versions of the software against
  1925. the same database version safely. Ledger-SMB checks the version of
  1926. the database and if the version is higher than the version of the
  1927. software that is running, will refuse to run.
  1928. Therefore although one strategy might be to run several front-end
  1929. web servers with Ledger-SMB, in reality this can be a bit of a problem.
  1930. One solution is to take half of the front-end servers off-line while
  1931. doing the initial upgrade, and then take the other offline to upgrade
  1932. when these are brought back online.
  1933. The database manager is less scalable in the sense that one cannot
  1934. just add more database servers and expect to carry on as normal. However,
  1935. aside from the known issues listed below, there are few performance
  1936. issues with it. If complex reports are necessary, these can be moved
  1937. to a replica database (perhaps using Slony-I).
  1938. If this solution is insufficient for database scalability, one might
  1939. be able to move staff who do not need real-time access to new entries
  1940. onto a PG-Pool/Slony-I cluster where new transactions are entered
  1941. on the master and other data is looked up on the replica. In certain
  1942. circumstances, one can also offload a number of other queries from
  1943. the master database in order to minimize the load. Ledger-SMB has
  1944. very few issues in the scalability of the application.
  1945. \subsubsection{Database Maintenance}
  1946. PostgreSQL uses a technique called Multi-version Concurrency Control
  1947. (MVCC) to provide a snapshot of the database at the beginning of a
  1948. statement or transaction (depending on the transaction isolation level).
  1949. When a row is updated, PostgreSQL leaves the old row in the database,
  1950. and inserts a new version of that row into the table. Over time, unless
  1951. those old rows are removed, performance can degrade as PostgreSQL
  1952. has to search through all the old versions of the row in order to
  1953. determine which one ought to be the current one.
  1954. Due to the way the SQL statements are executed in Ledger-SMB, most
  1955. inserts will also create a dead row.
  1956. A second problem occurs in that each transaction is given a transaction
  1957. id. These id's are numbered using 32-bit integers. If the transaction
  1958. id wraps around (prior to 8.1), data from transactions that appear
  1959. (due to the wraparound) to be in the future suddenly becomes inaccessible.
  1960. This problem was corrected in PostgreSQL 8.1, where the database will
  1961. refuse to accept new transactions if the transaction ID gets too close
  1962. to a wraparound. So while the problem is not as serious in 8.1, the
  1963. application merely becomes inaccessible rather than displaying apparent
  1964. data loss. Wraparound would occur after about a billion transactions
  1965. between all databases running on that instance of PostgreSQL.
  1966. Prior to 8.1, the main way to prevent both these problems was to run
  1967. a periodic vacuumdb command from cron (UNIX/Linux) or the task scheduler
  1968. (Windows). In 8.1 or later, autovacuum capabilities are part of the
  1969. back-end and can be configured with the database manager. See the
  1970. PostgreSQL documentation for treatment of these subjects.
  1971. In general, if performance appears to be slowly degrading, one should
  1972. try to run vacuumdb -z from the shell in order to attempt to reclaim
  1973. space and provide the planner with accurate information about the
  1974. size and composition of the tables. If this fails, then one can go
  1975. to other methods of determining the bottleneck and what to do about
  1976. it.
  1977. \subsubsection{Known issues}
  1978. The PostgreSQL planner assumes a minimum page size of ten pages for
  1979. a physically empty table. The reasoning behind this choice is that
  1980. a table could grow rapidly and one could end up with bad database
  1981. performance if the planner assumes a very small table.
  1982. However, if you end up with joins between a very large table with
  1983. millions of rows and a physically empty table, one can end up with
  1984. a very bad query plan. In this case, the planner will choose a nested
  1985. loop join and run through this loop for every row in the large table.
  1986. As a result, performance will suddenly drop once the large table becomes
  1987. too large to effectively do index scans of the join criteria on both
  1988. tables. This problem most often occurs when people have no warehouses,
  1989. departments, or projects defined and are running systems with a large
  1990. number of transactions (such as a point of sale environment).
  1991. Last time I saw this problem, the server would wait for thirty seconds
  1992. to display a new point of sale screen while the server CPU activity
  1993. would spike to 100\%.
  1994. One solution is to define one warehouse, department, and project,
  1995. and then run vacuumdb -z from the shell to force the planner to acknowledge
  1996. these tables as single-row tables. The other option is to go into
  1997. the source code and edit the database queries to omit unused tables.
  1998. \section{Customization Possibilities}
  1999. Ledger-SMB is designed to be customized relatively easily and rapidly.
  2000. In general, the source code is well written and compartmentalized.
  2001. This section covers the basic possibilities involving customization.
  2002. \subsection{Brief Guide to the Source Code}
  2003. Ledger-SMB is an application with over 34000 lines of code. While
  2004. it is not possible to cover the entire application here, a brief overview
  2005. of the source code is in order.
  2006. In the root of the install directory, one will find a setup.pl program,
  2007. a number of other .pl programs, and a number of directories. The setup.pl
  2008. program is used to update or install Ledger-SMB. The other .pl programs
  2009. provide a basic set of services for the framework (including authentication)
  2010. and then pass the work on to the data entry screen file in the bin
  2011. directory.
  2012. The bin directory contains another directory for each terminal type.
  2013. The main two offered are lynx and mozilla. Lynx would be used for
  2014. web browsers that do not support frames and is ideal for a text-mode
  2015. VGA terminal. Mozilla is the terminal type used for most other web
  2016. browsers. The perl files within these directories provides the user
  2017. interface of the software.
  2018. The css directory in the root install directory contains CSS documents
  2019. to provide various stylesheets one can select for changing various
  2020. aspects of the look and feel of the application.
  2021. The locale directory contains translation files that Ledger-SMB uses
  2022. to translate between different languages. One could add translations
  2023. to these files if necessary.
  2024. The LSMB directory is where the Perl modules reside that provide the
  2025. core business logic in Ledger-SMB. These modules provide functionality
  2026. such as form handling, email capabilities, and access to the database
  2027. through its at least partially object oriented API.
  2028. Finally, the sql directory provides the database schemas and upgrade
  2029. scripts.
  2030. \subsection{Data Entry Screens}
  2031. One can customize the data entry screens to optimize work flow, display
  2032. additional information, etc.
  2033. \subsubsection{Examples}
  2034. We set up hot keys for payment lines, automatically focused the keyboard
  2035. on the last partnumber field, removed separate print and post buttons
  2036. to ensure that invoices were always printed and posted together, and
  2037. removed the ability to print to the screen, and even the ability to
  2038. scan items in when an invoice was received (using a portable data
  2039. terminal) and import this data into Ledger-SMB. Finally we added the
  2040. ability to reconcile the till online in a paperless manner.
  2041. For another customer, we added the ability to print AR invoices in
  2042. plain text format and added templates (based on the POS sales template)
  2043. to do this.
  2044. \subsection{Extensions}
  2045. One can add functionality to the Perl modules in the LSMB directory
  2046. and often add missing functions easily.
  2047. \subsubsection{Examples}
  2048. For one customer, we added a module to take data from a portable data
  2049. terminal collected when inventory items were taken and use that to
  2050. add shrinkage and loss adjustments. We also extended the parts model
  2051. to add a check id flag (for alcohol sales) and added this flag to
  2052. the user interface.
  2053. For another customer, we added a complex invoice/packing slip tracking
  2054. system that allowed one to track all the printed documents associated
  2055. with an order or invoice.
  2056. \subsection{Templates}
  2057. As noted before templates can be modified or extended, though sometimes
  2058. this involves extending the user interface scripts. Most templates
  2059. are easy enough to modify.
  2060. \subsubsection{Examples}
  2061. For one customer we added text-only invoices for AR and AP transactions/Invoices
  2062. and an ability to use Javascript in them to automatically print them
  2063. on load.
  2064. \subsection{Reports}
  2065. The fact that all the data is available within the database manager
  2066. is a huge advantage of Ledger-SMB over Quickbooks and the like. The
  2067. rapid development of reports allows for one to easily develop reports
  2068. of any sort within Ledger-SMB.
  2069. \subsubsection{Examples}
  2070. For one customer, we developed a report of parts sold and received
  2071. during arbitrary time frames. The report allows one to go back and
  2072. look up the invoices involved.
  2073. \section{Integration Possibilities}
  2074. An open database system and programming API allows for many types
  2075. of integration. There are some challenges, but in the end, one can
  2076. integrate a large number of tools.
  2077. \subsection{Reporting Tools}
  2078. Any reporting tool which can access the PostgreSQL database can be
  2079. used with Ledger-SMB for custom reporting. These can include programs
  2080. like Microsoft Access and Excel (using the ODBC drivers), PgAccess
  2081. (A PostgreSQL front-end written in TCL/Tk with a similar feel to Access),
  2082. Rekall, Crystal Reports, OpenOffice and more.
  2083. \subsubsection{Examples}
  2084. We have created spreadsheets of the summaries of activity by day and
  2085. used the ODBC driver to import these into Excel. Excel can also read
  2086. HTML tables, so one can use PostgreSQL to create an HTML table of
  2087. the result and save it with a .xls extension so that Windows opens
  2088. it with Excel. These could then be served via the same web server
  2089. that serves Ledger-SMB.
  2090. \subsection{Line of Business Tools on PostgreSQL}
  2091. Various line of business tools have been written using PostgreSQL
  2092. in large part due to the fact that it is far more mature than MySQL
  2093. in areas relating to data integrity enforcement, transactional processing,
  2094. and the like. These tools can be integrated with Ledger-SMB in various
  2095. ways. One could integrate this program with the HERMES CRM framework,
  2096. for example.
  2097. \subsubsection{Known Issues}
  2098. Ledger-SMB uses a single 'id' sequence across many tables. At the
  2099. same time it is expected that these tables do not have identical id
  2100. values in their records as they are used as a sort of pseudo-foreign
  2101. key by the acc\_trans table which stores the financial transaction
  2102. information.
  2103. If the integration solution does not keep this in mind, it is possible
  2104. to create a situation where the account transactions are ambiguously
  2105. associated with a number of different types of financial transactions.
  2106. This would lead to a large number of problems.
  2107. \subsubsection{Strategies}
  2108. In general, it is advisable to run all such programs that benefit
  2109. from integration in the same database but under different schemas.
  2110. This allows PostgreSQL to become the main method of synchronizing
  2111. the data in real time. However, sometimes this can require dumping
  2112. the database, recreating the tables etc. in a different schema and
  2113. importing the data back into Ledger-SMB.
  2114. One possibility for this sort of integration is to use database triggers
  2115. to replicate the data between the applications in real-time. This
  2116. can avoid the main issue of duplicate id's. One issue that can occur
  2117. however relates to updates. If one updates a customer record in HERMES,
  2118. for example, how do we know which record to update in Ledger-SMB?
  2119. There are solutions to this problem but they do require some forethought.
  2120. A second possibility is to use views to allow one application to present
  2121. the data from the other as its own. This can be cleaner regarding
  2122. update issues, but it can also pose issues regarding duplicate id
  2123. fields.
  2124. \subsubsection{Examples}
  2125. Others have integrated L'ane POS and Ledger-SMB in order to make it
  2126. work better with touch screen devices. Still others have successfully
  2127. integrated Ledger-SMB and Interchange. In both cases, I believe that
  2128. triggers were used to perform the actual integration.
  2129. \subsection{Line of Business Tools on other RDBMS's}
  2130. Often there are requests to integrate Ledger-SMB with applications
  2131. like SugarCRM, OSCommerce, and other applications running on MySQL
  2132. or other database managers. This is a far more complex field and it
  2133. requires a great deal more effort than integrating applications within
  2134. the same database.
  2135. \subsubsection{Strategies}
  2136. Real-time integration is not always possible. MySQL does
  2137. not support the SQL extension SQL/MED (Management of External Data) that
  2138. supports non-MySQL data sources so it is not possible to replicate the
  2139. data in real-time. Therefore
  2140. one generally resorts to integrating the system using time-based updates.
  2141. Replication may be somewhat error-prone unless the database manager
  2142. supports triggers (first added to MySQL in 5.0) or other mechanisms
  2143. to ensure that all changed records can be detected and replicated.
  2144. In general, it is usually advisable to add two fields to the record--
  2145. one that shows the insert time and one that shows the last update.
  2146. Additionally, I would suggest adding additional information to the
  2147. Ledger-SMB tables so that you can track the source record from the
  2148. other application in the case of an update.
  2149. In general, one must write replication scripts that dump the information
  2150. from one and add it to the other. This must go both ways.
  2151. \subsubsection{Integration Products and Open Source Projects}
  2152. While many people write Perl scripts to accomplish the replication,
  2153. an open source project exists called DBI-Link. This package requires
  2154. PL/Perl to be installed in PostgreSQL, and it allows PostgreSQL to
  2155. present any data accessible via Perl's DBI framework as PostgreSQL
  2156. tables. DBI-Link can be used to allow PostgreSQL to pull the data
  2157. from MySQL or other database managers.
  2158. DBI-Link can simplify the replication process by reducing the operation
  2159. to a set of SQL queries.
  2160. \section{Customization Guide}
  2161. This section is meant to provide a programmer with an understanding
  2162. of the technologies enough information to get up to speed quickly
  2163. and minimize the time spent familiarizing themselves with the software.
  2164. Topics in this section are listed in order of complexity. As it appeals
  2165. to a narrower audience than previous discussions of this topic, it
  2166. is listed separately.
  2167. \subsection{General Information}
  2168. The main framework scripts (the ar.pl, ap.pl, etc. scripts found in
  2169. the root of the installation directory) handle such basic features
  2170. as instantiating the form object, ensuring that the user is logged
  2171. in, and the like. They then pass the execution off to the user interface
  2172. script (usually in the bin/mozilla directory).
  2173. Ledger-SMB in many ways may look sort of object oriented in its design,
  2174. but in reality, it is far more data-driven than object oriented. The
  2175. Form object is used largely as a global symbol table and also as a
  2176. collection of fundamental routines for things like database access.
  2177. It also breaks down the query string into sets of variables which
  2178. are stored in its attribute hash table.
  2179. In essence one can and often will store all sorts of data structures
  2180. in the primary Form object. These can include almost anything. It
  2181. is not uncommon to see lists of hashes stored as attributes to a Form
  2182. object.
  2183. \subsection{Customizing Templates}
  2184. Templates are used to generate printed checks, invoices, receipts,
  2185. and more in Ledger-SMB. Often the format of these items does not fit
  2186. a specific set of requirements and needs to be changed. This document
  2187. will not include \LaTeX{} or HTML instruction, but will include a
  2188. general introduction to editing templates. Also, this is not intended
  2189. to function as a complete reference.
  2190. Template instructions are contained in tags \textless?lsmb and ?\textgreater.
  2191. The actual parsing is done by the parse\_template function in LSMB/Form.pm.
  2192. \subsubsection{Page Breaks in \LaTeX{}}
  2193. The first tag one will see with \LaTeX{}\ templates is \textless?lsmb pagebreak
  2194. num1 num2 num3 ?\textgreater
  2195. \begin{itemize}
  2196. \item num1 represents characters per line
  2197. \item num2 represents lines on first page
  2198. \item num3 represents lines on second page.
  2199. \end{itemize}
  2200. The pagebreak block is terminated by \textless?lsmb end pagebreak ?\textgreater.
  2201. Any text within the pagebreak block is ignored by the template.
  2202. \subsubsection{Conditionals}
  2203. \begin{itemize}
  2204. \item \textless?lsmb if not varname ?\textgreater tells the parser to
  2205. include the next block only if varname was posted by the submitting
  2206. form (or set via the form hash elsewhere in the scripts). The block
  2207. ends with \textless?lsmb end varname ?\textgreater
  2208. \item \textless?lsmb if varname ?\textgreater tells the parser to include the
  2209. block if varname was posted in the submitting form (or set via
  2210. the form hash elsewhere in the scripts). The block ends with \textless?lsmb end
  2211. varname ?\textgreater
  2212. \item Lines conditionals are otherwise ignored by the parser.
  2213. \item Conditionals cannot be nested, but IF's can be nested inside loops.
  2214. \end{itemize}
  2215. \subsubsection{Loops}
  2216. \textless?lsmb foreach varname ?\textgreater is used to iterate through
  2217. a list of vars set by the user interface system (usually one of the
  2218. files under bin/mozilla (or otherwise). The block is repeated for
  2219. each varname in a list. Block ends with \textless?lsmb end varname ?\textgreater
  2220. \subsubsection{File Inclusion}
  2221. \begin{itemize}
  2222. \item Files may be included with the syntax \textless?lsmb include template\_name
  2223. ?\textgreater
  2224. where templatename is the name of the template within the current
  2225. template directory (usually templates/\$username/). Note that for \LaTeX\
  2226. templates, the input or include functionalities might be better suited for many
  2227. many things.
  2228. \item Cannot be used with conditionals
  2229. \item Filenames cannot use slashes (/) or .. due to directory transversal
  2230. considerations.
  2231. \item Files can force other files to be included, but the same file cannot
  2232. be included more than once.
  2233. \end{itemize}
  2234. \subsubsection{Cross-referencing and multiple passes of \LaTeX{}}
  2235. In \LaTeX{}\ cross-references require two passes with latex to resolve.
  2236. This is because the type is set page by page and the program really
  2237. doesn't know on which page a given reference will fall. This becomes
  2238. an even larger issue where floats are concerned as they can move between
  2239. pages for formatting reasons.
  2240. In rare cases, cross-references may point at incorrect pages even
  2241. with two passes (if the inclusion of the cross-reference data moves
  2242. the object to another page). In this case you will need to use three
  2243. passes of \LaTeX{}\ in order to have accurate references.
  2244. Ledger-SMB as of the time of this writing (2.6.8) only makes one pass
  2245. at the \LaTeX{}\ file. To force it to make more than one pass, open
  2246. Form.pm with your favorite text editor. Look for the line:
  2247. system(\char`\"{}latex --interaction=nonstopmode \$self-\textgreater$\lbrace$
  2248. tmpfile$\rbrace$\
  2249. \textgreater\ \$ self-\textgreater$\lbrace$ tmpfile$\rbrace$
  2250. .err\char`\"{});
  2251. Duplicate this line for two passes, or add two copies if you need
  2252. three passes.
  2253. \subsubsection{Variable Substitution}
  2254. The following format is used for variable substitution:
  2255. \begin{itemize}
  2256. \item \textless?lsmb varname options ?\textgreater Options are one or more
  2257. (whitespace separated) of:
  2258. \begin{itemize}
  2259. \item align=left/right/center
  2260. \item width=chars where chars is the width in characters before wrapping
  2261. \item offset=chars where chars is the number of spaces to (depending on
  2262. alignment).
  2263. \end{itemize}
  2264. \end{itemize}
  2265. \subsection{Customizing Forms}
  2266. Data entry forms and other user interface pieces are in the bin directory.
  2267. In Ledger-SMB 1.0.0 and later, symlinks are not generally used.
  2268. Each module is identified with a two letter combination: ar, ap, cp,
  2269. etc. These combinations are generally explained in the comment headers
  2270. on each file.
  2271. Execution in these files begins with the function designated by the
  2272. form->$\lbrace$action$\rbrace$ variable. This variable is usually
  2273. derived from configuration parameters in the menu.ini or the name
  2274. of the button that was clicked on to submit the previous page. Due
  2275. to localization requirements, the following process is used to determine
  2276. the appropriate action taken:
  2277. The \$locale-\textgreater getsub routine is called. This routine
  2278. checks the locale package to determine if the value needs to be translated
  2279. back into an appropriate LSMB function. If not, the variable is lower-cased,
  2280. and all spaces are converted into underscores.
  2281. In general there is no substitute for reading the code to understand
  2282. how this can be customized and how one might go about doing this.
  2283. \subsection{Customizing Modules}
  2284. The Perl Modules (.pm files) in the LedgerSMB directory contain the
  2285. main business logic of the application including all database access.
  2286. Most of the modules are relatively easy to follow, but the code quality
  2287. leaves something to be desired. The API calls themselves are
  2288. likely to be replaced in the future, so work on documenting API calls is
  2289. now focused solely on those calls that are considered to be stable.
  2290. At the moment, the best place to request information on the API's is on
  2291. the Developmers' Email List (\mailto{ledger-smb-devel@lists.sourceforge.net}).
  2292. Many of these modules have a fair bit of dormant code in them which
  2293. was written for forthcoming features, such as payroll and bills of
  2294. materials.
  2295. One can add a new module through the normal means and connect it to
  2296. other existing modules.
  2297. \subsubsection{Database Access}
  2298. The \$form object provides two methods for accessing the database.
  2299. The \$form-\textgreater dbconnect(\%myconfig) method commits each
  2300. individual statement as its own transaction. The \$form-\textgreater
  2301. dbconnect\_noauto(\%myconfig) method requires a manual commit. Both
  2302. these functions are thin wrappers around the standard Perl DBI operations.
  2303. \subsection{CLI Examples}
  2304. Louis Moore contributed some SQL-Ledger CLI examples that still work for
  2305. LedgerSMB. You can find his page at \url{http://www.sql-ledger.org/cgi-bin/nav.pl?page=contrib/moore.html&title=Louis\%20B.\%20Moore}.
  2306. \clearpage
  2307. \part{Appendix}
  2308. \appendix
  2309. %dummy comment inserted by tex2lyx to ensure that this paragraph is not empty
  2310. \section{Where to Go for More Information}
  2311. There are a couple of relevant sources of information on Ledger-SMB
  2312. in particular.
  2313. The most important resources are the LedgerSMB web site
  2314. (\url{http://www.ledgersmb.org}) and the email lists found at our Sourceforge
  2315. site.
  2316. In addition, it is generally recommended that the main bookkeeper
  2317. of a company using Ledger-SMB work through at least one accounting
  2318. textbook. Which textbook is not as important as the fact that a textbook
  2319. is used.
  2320. \section{Quick Tips}
  2321. \subsection{Understanding Shipping Addresses and Carriers}
  2322. Each customer can have a default shipping address. This address is
  2323. displayed prominantly in the add new customer screen. To change the
  2324. shipping address for a single order, one can use the ship to button
  2325. at the bottom of the quote, order, or invoice screen.
  2326. The carrier can be noted in the Ship Via field. However, this is a
  2327. freeform field and is largely used as commentary (or instructions
  2328. for the shipping crew).
  2329. \subsection{Handling bad debts}
  2330. In the event that a customer's check bounces or a collection requirement
  2331. is made, one can flag the customer's account by setting the credit
  2332. limit to a negative number.
  2333. If a debt needs to be written off, one can either use the allowance
  2334. method (by writing it against the contra asset account of \char`\"{}Allowance
  2335. for Bad Debts\char`\"{} or using the direct writeoff method where
  2336. it is posted as an expense.
  2337. \section{Step by Steps for Vertical Markets}
  2338. \subsection{Common Installation Errors}
  2339. \begin{itemize}
  2340. \item Ledger-SMB is generally best installed in its own directory outside
  2341. of the wwwroot directory. While it is possible to install it inside
  2342. the wwwroot directory, the instructions and the faq don't cover the
  2343. common problems here.
  2344. \item When the chart of accounts (COA) is altered such that it is no longer
  2345. set up with appropriate items, you can make it impossible to define
  2346. goods and services properly. In general, until you are familiar with
  2347. the software, it is best to rename and add accounts rather than deleting
  2348. them.
  2349. \end{itemize}
  2350. \subsection{Retail With Light Manufacturing}
  2351. For purposes of this example we will use a business that assembles
  2352. computers and sells them on a retail store.
  2353. \begin{enumerate}
  2354. \item Install Ledger-SMB.
  2355. \item Set preferences, and customize chart of accounts.
  2356. \begin{enumerate}
  2357. \item Before customizing the COA it is suggested that you consult an accountant.
  2358. \end{enumerate}
  2359. \item Define Goods, Labor, and Services as raw parts ordered from the vendors.
  2360. \begin{itemize}
  2361. \item These are located under the goods and services menu node.
  2362. \end{itemize}
  2363. \item Define assemblies.
  2364. \begin{itemize}
  2365. \item These are also located under goods and services.
  2366. \item Component goods and services must be defined prior to creating assembly.
  2367. \end{itemize}
  2368. \item Enter an AP Invoice to populate inventory with proper raw materials.
  2369. \begin{itemize}
  2370. \item One must generally add a generic vendor first. The vendor is added
  2371. under AP-\textgreater Vendors-\textgreater Add Vendor.
  2372. \end{itemize}
  2373. \item To pay an AP invoice like a check, go to cash-$>$payment. Fill out
  2374. approrpiate fields and click print.
  2375. \begin{itemize}
  2376. \item Note that one should select an invoice and enter in the payment amount
  2377. in the appropriate line of the invoice list. If you add amounts to
  2378. the master amount list, you will find that they are added to the amount
  2379. paid on the invoice as a prepayment.
  2380. \item The source field is the check number.
  2381. \end{itemize}
  2382. \item Stock assemblies
  2383. \item One can use AR Invoices or the POS interface to sell goods and services.
  2384. \begin{itemize}
  2385. \item Sales Invoice
  2386. \begin{itemize}
  2387. \item Can be generated from orders or quotations
  2388. \item Cannot include labor/overhead except as part of an assembly
  2389. \item One can make the mistake of printing the invoice and forgetting to
  2390. post it. In this event, the invoice does not officially exist in the
  2391. accounting system.
  2392. \item For new customers, you must add the customer first (under AR-\textgreater
  2393. Customers-\textgreater Add Customer.
  2394. \end{itemize}
  2395. \item POS Interface
  2396. \begin{itemize}
  2397. \item Cannot include labor/overhead except as part of an assembly
  2398. \item Printing without posting is often even easier in the POS because of
  2399. the rapid workflow. Yet it is just as severe a problem.
  2400. \end{itemize}
  2401. \item Ecommerce and Mail Order Operations
  2402. \begin{itemize}
  2403. \item See the shipping workflow documentation above.
  2404. \end{itemize}
  2405. \item Customers are set up by going to AR-\textgreater Customers-\textgreater
  2406. Add Customer (or the equivalent localized translation). The appropriate
  2407. fields are filled out and the buttons are used at the bottom to save
  2408. the record and optionally use it to create an invoice, etc.
  2409. \begin{itemize}
  2410. \item Saving a customer returns to the customer screen. After the appropriate
  2411. invoice, transaction, etc. is entered and posted, Ledger-SMB will
  2412. return to the add customer screen.
  2413. \end{itemize}
  2414. \end{itemize}
  2415. \item One can use the requirements report to help determine what parts need
  2416. to be ordered though one cannot generate PO's directly from this report.
  2417. \end{enumerate}
  2418. Note, the needs of Ledger-SMB are mostly useful for light manufacturing
  2419. operations (assembling computers, for example). More manufacturing
  2420. capabilities are expected to be released in the next version.
  2421. A custom assembly is a bit difficult to make. One must add the assembly
  2422. prior to invoice (this is not true of goods and services). If the
  2423. assembly is based on a different assembly but may cost more (due to
  2424. non-standard parts) you can load the old assembly using Goods and
  2425. Services-\textgreater Reports-\textgreater Assemblies and then make
  2426. necessary changes (including to the SKU/Partnumber) and save it as
  2427. new.
  2428. Then one can add it to the invoice.
  2429. \section{Glossary}
  2430. \begin{description}
  2431. \item [{BIC}] Bank Identifier Code is often the same as the S.W.I.F.T.
  2432. code. This is a code for the bank a customer uses for automated money
  2433. transfers.
  2434. \item [{COGS}] is Cost of Goods Sold. When an item is sold, then the expense
  2435. of its purchase is accrued as attached to the income of the sale.
  2436. It is tracked as COGS.
  2437. \item [{Credit}] : A logical transactional unit in double entry accounting.
  2438. It is the opposite of a debit. Credits affect different account types
  2439. as follows:
  2440. \begin{description}
  2441. \item [{Equity}] : Credits are added to the account when money is invested
  2442. in the business.
  2443. \item [{Asset}] : Credits are added when money is deducted from an asset
  2444. account.
  2445. \item [{Liability}] : Credits are added when money is owed to the business
  2446. account.
  2447. \item [{Income}] : Credits are added when income is earned.
  2448. \item [{Expense}] : Credits are used to apply adjustments at the end of
  2449. accounting periods to indicate that not all the expense for an AP
  2450. transaction has been fully accrued.
  2451. \end{description}
  2452. \item [{Debit}] : A logical transactional unit in double entry accounting
  2453. systems. It is the opposite of a credit. Debits affect different account
  2454. types as follows:
  2455. \begin{description}
  2456. \item [{Equity}] : Debits are added when money is paid to business owners.
  2457. \item [{Asset}] : Debits are added when money is added to an account.
  2458. \item [{Liability}] : Debits are added when money that is owed is paid
  2459. off.
  2460. \item [{Income}] : Debits are used to temporarily adjust income to defer
  2461. unearned income to the next accounting period.
  2462. \item [{Expense}] : Debits are added as expenses are incurred.
  2463. \end{description}
  2464. \item [{IBAN}] International Bank Account Number is related to the BIC
  2465. and is used for cross-border automated money transfers.
  2466. \item [{List}] Price is the recommended retail price.
  2467. \item [{Markup}] is the percentage increase that is applied to the last
  2468. cost to get the sell price.
  2469. \item [{ROP}] Re-order point. Items with fewer in stock than this will
  2470. show up on short reports.
  2471. \item [{Sell}] Price is the price at which the item is sold.
  2472. \item [{SKU}] Stock Keeping Unit: a number designating a specific product.
  2473. \item [{Source}] Document : a paper document that can be used as evidence
  2474. that a transaction occurred. Source documents can include canceled
  2475. checks, receipts, credit card statements and the like.
  2476. \item [{Terms}] is the number of days one has to pay the invoice. Most
  2477. businesses abbreviate the terms as Net n where n is the number of
  2478. days. For example, Net 30 means the customer has 30 days to pay the
  2479. net due on an invoice before it is late and incurs late fees. Sometimes
  2480. you will see 2 10 net 30 or similar. This means 2\% discount if paid within
  2481. 10 days but due within 30 days in any case.
  2482. \end{description}
  2483. \input{fdl.tex}
  2484. \end{document}