=head1 NAME ic_howto_qb - Interchange + QuickBooks HOWTO =head1 DESCRIPTION =head1 Introduction =head2 Summary Description Interchange QuickBooks -- QuickBooks support for transactions and items =head2 Audience Users who already have Quickbooks setup and are familiar with it, in addition to having the foundation (or other) catalog correctly working. =head2 Contact the author If you find any spelling errors, technical slip-ups, mistakes, subliminal messages, or if you wish to send feedback, critique, remarks, comments, or if you wish to contribute examples, instructions for alternative platforms, chapters, or other material, please do so. The preferred method of submitting changes is in the form of a context diff against the SDF source file (ic_howto_qb.sdf). Please address your correspondence to: Volunteer Maintainer, Dan Browning I or Original Author, Mike Heins I =head2 Version This document describes software based on Interchange 4.5 and later. =head1 Description Interchange is a business-to-business and business-to-consumer internet ordering and cataloguing product. It has the ability to take orders via the World Wide Web, and store transaction data. This document describes how to interface Interchange with QuickBooks, the popular small-business accounting program from Intuit. QuickBooks has an import/export format called IIF, a mnemonic for Intuit Interchange Format. Fitting, eh? The standard capabilities of Interchange allow production of IIF files for transaction passing. With some support from Interchange UserTags, it can even import and export item listings. =head1 Contents The extension files can be found in the Interchange tarball under the 'extensions/quickbooks' directory. The following files are used with this extension: usertag/import_quicken_items UserTag for importing items usertag/export_quicken_items UserTag for exporting items pages/admin/quickbooks/* Menu support for Interchange UI qb.catalog.cfg Quickbooks configuration. =head1 Installation To set up this extension, the basic steps are: =over 4 =item * Create and copy directories and files. =item * Add additional database fields. =item * Modify catalog.cfg with additions. =item * Add "quickbooks" order route to checkout pages. =item * Restart Interchange. =item * Export your items from Interchange catalog (or import your existing QuickBooks items to Interchange). =item * Test. =back =head2 Terms and locations Several terms are used in the examples. =over 4 =item Catalog Directory This is the main directory for the catalog, where catalog.cfg resides. It will have a NAME, the name for the catalog. (Some common Interchange demo names are foundation, construct, barry, and simple.) Common locations: /var/lib/interchange/NAME /usr/local/interchange/catalogs/NAME $HOME/catalogs/NAME We will use the path /var/lib/interchange/foundation in these examples. =item Interchange software directory This is the main directory for your Interchange server, where the file interchange.cfg resides. Common locations: /usr/lib/interchange /usr/local/interchange $HOME/ic We will use the path /usr/lib/interchange in these examples. =item Interchange tarball directory The quickbooks files are located in the untarred distribution file, before installation of Interchange is performed. =item Interchange User The Interchange daemon runs as a user ID that cannot be root. It will require write permission on directories it must modify to do its work. We will use the user ID interch in these examples. =back =head2 Create and copy directories and files This extension requires you to add some files to your catalog. It is assumed you have tools and knowledge to create directories with the proper permissions. Any directories that will contain varying files like order transaction logs will require write permission for the Interchange daemon user; pages and configuration only need have read permission. =head2 Quick Installation Script This script will install the necessary files for you, provided that you modify the variables to your environment. Alternately, you can follow the more detailed installation instructions that follow it. Note that if you are not using a 4.9.8+ version of Interchange, you will need to manually install the qb_safe.filter by copying it from the 4.9.8 code/Filter/qb_safe.filter into your Interchange version. # Modify these three variables to match your environment. export QB=/path/to/interchange/extensions/quickbooks export VENDROOT=/usr/local/interchange export CATROOT=/home/interch/catalogs/foundation mkdir -p $CATROOT/include/menus $CATROOT/vars cp -r $QB/TRANS_QUICKBOOKS \ $CATROOT/vars cp -r $QB/pages/admin/quickbooks \ $CATROOT/pages/admin cp -i $QB/usertag/* \ $VENDROOT/code/UI_Tag # Alternate usertag installation style: # #mkdir -p $CATROOT/usertags/global #cp -i $QB/usertag/* \ # $CATROOT/usertags/global # # Then include the global/*.tag in your interchange.cfg # Variables that optionally modify the export process, along with # their help entries. cat $QB/products/variable.txt.append >> \ $CATROOT/products/variable.txt cat $QB/products/mv_metadata.asc.append >> \ $CATROOT/products/mv_metadata.asc # Menu entries: start with the existing menu, then add ours. cp -i $VENDROOT/lib/UI/pages/include/menus/Admin.txt \ $CATROOT/include/menus cat $QB/menus/Admin.txt.append >> \ $CATROOT/include/menus/Admin.txt # Some configuration changes. cat >> $CATROOT/catalog.cfg < It will provide options for importing and exporting items. This is necessary so QuickBooks will be able to take orders for your items. QuickBooks uses the product "name" as an SKU, along with an integer reference number. Either you need to make your SKUs match the integer reference number, or you must ensure your product title is unique. =head2 Test Place a test order on your Interchange catalog once you have finished installing. You should find a file in the orders directory with the name qbYYYYMMDD.iif. (YYYY=year, MM=month, DD=day.) Transfer this file to your QuickBooks machine and run File/Import and select that file as the source. This should import the customer and order into the system. If it doesn't work, it may be due to lack of sales tax or shipping definitions, discussed below. =head1 Usage =head2 Accessing Admin UI Features A typical installation will cause the Administrative User Interface Features to become available via the top level menu: =over 4 =item * Login to the Admin UI =item * Administration =item * Quickbooks =back You should then be presented with a menu of the Admin UI features. =head2 Generating IIF Files To generate the IIF files, access the corresponding page from the Admin UI Quickbooks Menu (Administration -> Quickbooks -> Generate IIF Files). You will be presented with a query tool. Select the query options that you would like and submit your query. Among the query options, you have the option to input a QB transaction number. This will be the first number that is used when generating the IIF files, and it will be incremented for each sequential order in the query. You will be notified of its success or failure. The resulting page will: =over 4 =item * Inform you of the success or failure of the query. =item * Provide a link to the "results" IIF file (which includes all of the orders found by the query). Note that this "results" IIf file is overwritten every time a query is run. =item * Provide a link for each IIF file (one per order). This can be used as a backup, or for importing one-by-one instead of all at once. =back =head1 Discussion The interface provided works for the sample company data distributed with QuickBooks. There are certain requirements to make sure it works in your environment. Also, you can change the configuration by editing the file etc/trans_quickbooks to suit your IIF file needs. =head2 Sales Tax QuickBooks has a taxing system whereby tax rates are defined by customer location. There is usually also a generic Sales Tax Item, such as contained in the sample company data. This allows Interchange to calculate the sales tax. If that item is not present then you will need to create it, or specify your tax item using the QB_SALES_TAX_ITEM variable. =head2 Shipping Interchange will add a generic item Shipping to each order that has a shipping cost. Its MEMO field will contain the text description of the mode. If that item is not in your QuickBooks item definitions, then you must create it, or specify your shipping item using the QB_SHIPPING_ITEM variable. =head2 Customer Imports To generate a QuickBooks transtype of INVOICE, a CUSTOMER is required. Interchange outputs a CUST IIF record for each sale with the customer information. Since QuickBooks uses the customer name or company to generate the unique listing, we place the Interchange username in parentheses after the company or name. =head2 IIF generation at time of order As of 4.9, the IIF generation was moved from an order route into the Admin UI. This was done so that the IIF generation process could be fine tuned without restarting Interchange and placing an order. If you need the IIF file generated at the time of order, you can still access the pre-4.9.6 files in extensions/quickbooks/legacy. Credits =over 4 =item * B: This document was copied from the original POD documentation (extensions/quickbooks/ic_qb.pod) written by Mike Heins I. =item * B: Updated by Dan Browning I. =back Document history =over 4 =item * July 20, 2002. Initial revision. =back Resources Documentation =over 4 =item * What are the IIF File Headers? L =item * Also see the Quickbooks Help item, "Reference guide to import files" =back Copyright 2002-2004 Interchange Development Group. Freely redistributable under terms of the GNU General Public License.