diff options
Diffstat (limited to 'doc/en/details-impexp.docbook')
| -rw-r--r-- | doc/en/details-impexp.docbook | 1103 |
1 files changed, 1103 insertions, 0 deletions
diff --git a/doc/en/details-impexp.docbook b/doc/en/details-impexp.docbook new file mode 100644 index 0000000..1dafbdd --- /dev/null +++ b/doc/en/details-impexp.docbook @@ -0,0 +1,1103 @@ +<?xml version="1.0" encoding="UTF-8"?> +<chapter id="details.impexp"> +<chapterinfo> + <authorgroup> + <author> + <firstname>Ace</firstname> + <surname>Jones</surname> + <affiliation> + <address><email>acejones@users.sourceforge.net</email></address> + </affiliation> + </author> + </authorgroup> + <date>2009-07-30</date> + <releaseinfo>1.0</releaseinfo> +</chapterinfo> + +<title>Importing and Export</title> + +<sect1 id="details.impexp.gnucash"> +<sect1info> + <author> + <firstname>Tony</firstname> + <surname>Bloomfield</surname> + <affiliation> + <address><email>tonybloom@users.sourceforge.net</email></address> + </affiliation> + </author> +</sect1info> + +<title>GnuCash Importer</title> + +<sect2> +<title>GnuCash Files</title> + +<para> + The &kappname; GnuCash importer handles direct reading of standard (&XML;) + files as produced by GnuCash versions 1.8 and 2.0. The following are not + supported: +</para> + +<itemizedlist> + <listitem><para>import of database (Postgres) data</para></listitem> + <listitem><para>import of 'multi-book' files</para></listitem> + <listitem><para>import into an existing &kappname; file</para></listitem> + <listitem><para>import of small-business specific features (Employees, + Invoices, etc.)</para></listitem> + <listitem><para>export to GnuCash files.</para></listitem> +</itemizedlist> + +<para> + The import will probably only work correctly if presented with a valid + file. It is recommended that the GnuCash 'Check & Repair All' function (in + the Actions menu) be run before attempting to import. +</para> + +<para> + Files can be opened by specifying the file name on the command line + (<command>kmymoney <filepath></command>), or by means of the &kappname; + <menuchoice> + <shortcut><keycombo><keysym>Ctrl-O</keysym></keycombo></shortcut> + <guimenu>File</guimenu><guimenuitem>Open</guimenuitem> + </menuchoice> or + <menuchoice> + <guimenu>File</guimenu><guimenuitem>Import</guimenuitem> + </menuchoice> menu items. +</para> + +<para> + The similarity between the two products means that much day-to-day data can be + imported in a straightforward fashion. However, there are some areas where + differences arise, and various options are provided to deal with these. The + following sections will describe some of these differences; understanding them + should lead to a smoother importation. +</para> +</sect2> + +<sect2> +<title>Similarities, Differences, and Terminology</title> + +<sect3> +<title>Small Business Usage</title> + +<para> + It should be noted that &kappname; is a <emphasis>personal</emphasis> finance + manager, and as such, does not directly support any of the business features + of GnuCash, such as tax tables, payroll, and tracking of lots. Any Accounts + Payable or Receivable accounts found in a file will be imported as Liability + or Asset accounts respectively. +</para> +</sect3> + +<sect3> +<title>Accounts</title> + +<sect4> +<title>Account types</title> + +<para> + For both products, the highest level of structure in the file is the + account. &kappname; supports 5 main types of account: Asset, Liability, + Income, Expense and Equity, each of which may have various subtypes, e.g., + Checking, Credit Card, &etc;. &kappname; includes a 'standard' account for + each of these five types, and all other accounts are held subordinate to one + of these. &kappname; enforces more consistency (or less flexibility, depending + on your point of view) between account types than does GnuCash, and the + importer will correct any inconsistencies it detects. This may result in a + slightly different account structure, though this can, within reason, be + amended after the import is complete. +</para> +</sect4> + +<sect4> +<title>Categories</title> + +<para> + &kappname; uses the term Category to denote an account of an Income or Expense + type. Unlike GnuCash, these are not considered as 'ledger' accounts, and entry + of transactions folder into categories is not supported; allocations are made + during transaction entry into other account types. +</para> +</sect4> + +<sect4> +<title>Structure and Placeholders</title> + +<para> + GnuCash supports the use of Placeholder accounts. In effect, these are just + read-only accounts into which no transactions can be entered, but which + function in an analogous fashion to folders in a folder structure, as a + holder for other accounts. Though &kappname; does not support this feature as + such, it does provide a parent/child account relationship, so the importer + simulates placeholders by creating empty accounts. +</para> +</sect4> + +<sect4> +<title>Account Type map</title> + +<informaltable frame='all'> +<tgroup cols='2' align='left' colsep='1' rowsep='1'> +<thead> + <row> + <entry>GnuCash type</entry><entry>&kappname; type</entry> + </row> +</thead> +<tbody> + <row> + <entry>BANK</entry><entry>Checking</entry> + </row> + <row> + <entry>CHECKING</entry><entry>Checking</entry> + </row> + <row> + <entry>SAVINGS</entry><entry>Savings</entry> + </row> + <row> + <entry>ASSET</entry><entry>Asset</entry> + </row> + <row> + <entry>CASH</entry><entry>Cash</entry> + </row> + <row> + <entry>CURRENCY</entry><entry>Cash</entry> + </row> + <row> + <entry>MONEYMRKT</entry><entry>MoneyMarket</entry> + </row> + <row> + <entry>STOCK</entry><entry>Stock</entry> + </row> + <row> + <entry>MUTUAL</entry><entry>Stock</entry> + </row> + <row> + <entry>EQUITY</entry><entry>Equity</entry> + </row> + <row> + <entry>LIABILITY</entry><entry>Liability</entry> + </row> + <row> + <entry>CREDIT</entry><entry>CreditCard</entry> + </row> + <row> + <entry>INCOME</entry><entry>Income</entry> + </row> + <row> + <entry>EXPENSE</entry><entry>Expense</entry> + </row> + <row> + <entry>RECEIVABLE</entry><entry>Asset</entry> + </row> + <row> + <entry>PAYABLE</entry><entry>Liability</entry> + </row> +</tbody> +</tgroup> +</informaltable> +</sect4> +</sect3> + +<sect3> +<title>Transactions and Splits</title> + +<sect4> +<title>Balanced transactions</title> + +<para> + As with GnuCash, data is entered in the form of transactions, each generally + consisting of 2 or more split entries. In fact, valid GnuCash transactions + will always contain at least 2 splits, and to conform to GnuCash's + double-entry bookkeeping standard, these must be in monetary balance (i.e., + they must balance out to zero). &kappname; encourages, but does not enforce, + this standard, but any imported transaction which is not balanced will be + marked in the ledger view as having a problem. +</para> +</sect4> + +<sect4> +<title>Payees</title> + +<para> + &kappname; prefers that all transactions have a Payee (a generic term that + encompasses both payees and payers), and unlike GnuCash, a list of these + payees is maintained. Payee names are generated by the importer from the + GnuCash transaction's Description field. +</para> +</sect4> + +<sect4> +<title>Transfers</title> + +<para> + &kappname; uses the term Transfer to describe a transaction which does not + involve a Category, but only transfers money between Asset and/or Liability + accounts. +</para> +</sect4> + +<sect4> +<title>Reconcile</title> + +<para> + &kappname; provides an account reconciliation function similar to that of + GnuCash, and the corresponding transaction status will be imported. +</para> +</sect4> +</sect3> + +<sect3> +<title>Commodities</title> + +<para> + GnuCash uses the term Commodity to cover both currencies and non-currency + assets. These are treated separately in &kappname;. +</para> + +<sect4> +<title>Currencies</title> + +<para> + &kappname; has built-in support for all foreign + <link linkend="details.currencies">currency</link> types. &kappname; also + requires that the user specify a base currency, this being the default + currency for new accounts. The importer will attempt to determine the most + likely base currency, though this choice may be rejected in favour of an + alternative. +</para> + +<para> + (NOTE: &kappname; does not currently support accounts denominated in 'defunct' + currencies (except those replaced by the Euro). At present, it will be + necessary to remove any such accounts from your GnuCash file before + importing. We hope to improve on this situation in a future release.) +</para> +</sect4> + +<sect4 id="gncsecurities"> +<title>Securities and Investments</title> + +<para> + Non-currency assets (normally stocks and bonds) are called Securities by + &kappname;, and represent the main difference between the two products, in + that &kappname; requires any account denominated in a security to be + subordinate to an Investment Account. This is described in more detail in the + chapter on <link linkend="details.investments">Investments</link>. Though + users may have implemented such a relationship, GnuCash imposes no defined + structure on it, so the importer is unable to detect it and perform an + automatic conversion. Three options are therefore made available: +</para> + +<itemizedlist> + <listitem> + <para>Create a separate Investment account for each security, with the same + name as the security</para> + </listitem> + + <listitem> + <para>Create a single Investment account which will act as 'parent' for all + security accounts</para> + </listitem> + + <listitem> + <para>Create several Investment accounts, and assign securities to them as + directed by the user.</para> + </listitem> +</itemizedlist> + +<para> + It depends entirely on user requirements which of these options is relevant in + each situation, and in some cases, manual restructuring of accounts after + importation may be necessary. +</para> +</sect4> + +<sect4> +<title>Prices and currency rates</title> + +<para> + Security prices and currency exchange rates as displayed in the GnuCash Price + Editor will be imported. In addition, price and rate entries will be generated + from all transactions involving securities and multiple currencies. +</para> +</sect4> + +<sect4 id="details.impexp.gncquotes"> +<title>Online Quotes</title> + +<para> + For obtaining online price and currency rate quotations, GnuCash uses a + package called Finance::Quote. Recent versions of &kappname; contain support + for this package for obtaining stock quotes, and this will be used by default + when importing data. You may however elect to convert to the native method + used by &kappname; which is covered in more detail in + <link linkend="details.investments.onlinequotes">online quotes</link>. +</para> + +<para> + If you choose to do so, the following dialog will allow selection of a + 'native' &kappname; price source, or a user-defined source, for each account + for which online quotes are required. However, the stock (ticker) symbol will + be imported unchanged. Since this symbol will almost certainly be different in + the two packages, it will need to be manually edited after completion of the + import process. Future currency rate updates will not use Finance::Quote, and + will always use the native retrieval method. +</para> + +<para> + <screenshot> + <mediaobject> + <imageobject> + <imagedata fileref="gnucash-select_price_source.png" format="PNG" /> + </imageobject> + </mediaobject> + </screenshot> +</para> +</sect4> +</sect3> + +<sect3 id="gncschedules"> +<title>Scheduled Transactions</title> + +<para> + &kappname; does not retain the separation made in GnuCash between template + transactions and their frequency of occurrence. Transaction data will be + duplicated if the same template is used in different schedules, but this is + not likely to be of great significance. +</para> + +<sect4> +<title>Schedule types</title> + +<para> + &kappname; classifies all schedules as one of three types, Bills, Deposits, or + Transfers. Since GnuCash does not make such a distinction, the importer + attempts to determine the classification from the accounts and direction of + money movements. It may be that in some cases incorrect assumptions are made, + and these will need manual correction. +</para> +</sect4> + +<sect4> +<title>Suspect Schedules</title> + +<para> + Some features of GnuCash scheduled transactions are not available in + &kappname;, so the importer tries in each case to reach a reasonable + compromise in converting the data. These transactions will be flagged as + suspect, and the user will be given the option of editing them directly during + the import process. Examples of situations which may cause this are: +</para> + +<itemizedlist> + <listitem> + <para>some frequency intervals supported in GnuCash are not currently + available in &kappname;</para> + </listitem> + + <listitem> + <para>&kappname; does not support the use of formulae and variables in + amount fields</para> + </listitem> + + <listitem> + <para>complex cases which have not yet been identified for import.</para> + </listitem> +</itemizedlist> + +<para> + Despite best efforts, it is possible that, due to the many options involved, a + scheduled transaction may cause a fatal error within &kappname;. If this sort + of problem seems to be occurring, the importer offers the option to drop all + suspect schedules. +</para> +</sect4> +</sect3> + +<sect3> +<title>Reports</title> + +<para> + &kappname; provides a comprehensive selection of configurable reports, + described in more detail in <link linkend="details.reports">Reports.</link> + These will not necessarily, however, match precisely those reports available + in GnuCash. +</para> +</sect3> +</sect2> + +<sect2> +<title>Selecting Importer Options</title> + +<para id="details.impexp.gncoptions"> + <screenshot> + <mediaobject> + <imageobject> + <imagedata fileref="gnucash-import_options.png" format="PNG" /> + </imageobject> + </mediaobject> + </screenshot> +</para> + +<sect3> +<title>Investment Handling</title> + +<para> + See <link linkend="gncsecurities">"Securities and Investments"</link> above. +</para> +</sect3> + +<sect3> +<title>Online Quotes</title> + +<para> + Turn this off if you wish to use the native method for future online price + quotes. +</para> + +<para> + See <link linkend="details.impexp.gncquotes">"Online Quotes"</link> above. +</para> +</sect3> + +<sect3> +<title>Scheduled Transactions</title> + +<para> + See <link linkend="gncschedules">"Scheduled Transactions"</link> above. +</para> +</sect3> + +<sect3> +<title>Decoding Options</title> + +<para> + If your native language is written in letters or symbols which are different + from those used in the 'Latin' languages (i.e., generally Western European), + these are represented in a special fashion ('encoded') in your GnuCash file. + If these letters are not displayed correctly on your screen, then they must be + decoded. Currently, it is often not possible to detect accurately which form + of decoding must be used, so you may need to set this option and select an + entry from the list. In general, the first item in the list will be that + which is considered appropriate for your locale (i.e., the country and + language which was selected as native when your operating system was + installed), so this should be tried first. Since the import process does not + overwrite your GnuCash file, you are free to experiment with any of these + selections. +</para> +</sect3> + +<sect3> +<title>Transaction Notes option</title> + +<para> + Under some usage conditions, non-split GnuCash transactions may contain + residual, often incorrect, memo data which is not normally visible to the + user. When imported into &kappname; however, due to display differences, this + data can become visible. Often, these transactions will have a Notes field + describing the real purpose of the transaction. If this option is selected, + these notes, if present, will be used to override the extraneous memo data. +</para> +</sect3> + +<sect3> +<title>Debug Options</title> + +<para> + These need only be used in the event of import problems. If you have such + problems, you should also report them to the &kappname; developer list + &devlist;. Note that the traces produced by these options may contain data of + a confidential nature, and the Anonymize option should be used if they are to + be made publicly available. +</para> +</sect3> +</sect2> + +<sect2> +<title>Import Report</title> + +<para> + At the end of processing, the importer produces a report showing the number of + different entities processed, and any errors or anomalies encountered. This + report will be displayed on screen, and may be saved to a file for later + review. A full report may contain the following sections: +</para> + +<itemizedlist> + <listitem> + <para>Record counts</para> + </listitem> + + <listitem> + <para>Inconsistencies in account types and actions taken</para> + </listitem> + + <listitem> + <para>Details of suspect schedules</para> + </listitem> +</itemizedlist> + +<para> + <screenshot> + <mediaobject> + <imageobject> + <imagedata fileref="gnucash-report.png" format="PNG" /> + </imageobject> + </mediaobject> + </screenshot> +</para> +</sect2> +</sect1> + +<sect1 id="details.impexp.qifimp"> +<sect1info> + <author> + <firstname>Thomas</firstname> + <surname>Baumgart</surname> + <affiliation> + <address><email>ipwizard@users.sourceforge.net</email></address> + </affiliation> + </author> +</sect1info> + +<title>QIF Importer</title> + +<sect2> +<title>QIF format considered harmful</title> + +<para> + Generally speaking, the QIF format should be avoided wherever possible. It is + a poor choice for transporting financial data. Among other things, QIF suffers + from these problems: +</para> + +<itemizedlist> + <listitem> + <para>Lack of standardized format: Different versions of the same program + will impart different meanings to the same element.</para> + </listitem> + + <listitem> + <para>Lack of transaction identifier: Because there is no ID number + associated with each transaction, matching duplicate transactions is + haphazard at best.</para> + </listitem> + + <listitem> + <para>Lack of expressiveness: The grammar is really simple, and cannot + portray the depth of financial information found in today's financial + environment.</para> + </listitem> +</itemizedlist> + +<para> + This is generally why Intuit stopped supporting QIF input at all with Quicken + 2005. If you have the option of getting data some other way, like OFX, always + choose that option. +</para> +</sect2> + +<sect2> +<title>How to import a QIF file</title> + +<para> + To import a QIF file, first ensure you have a valid &kappname; file open. + Then select <guimenuitem>Import</guimenuitem> <guimenuitem>QIF</guimenuitem> + from the <guimenu>File</guimenu> menu. +</para> + +<para> + <screenshot> + <mediaobject> + <imageobject> + <imagedata fileref="qifopen.png" format="PNG" /> + </imageobject> + </mediaobject> + </screenshot> +</para> + +<para> + The resulting dialog prompts for the QIF filename allowing you to locate the + file by clicking on the <guibutton>Browse</guibutton> button. +</para> + +<para> + Also, &kappname; differentiates between the import of a bank statement file + and historic data exported from another application. The default is to import + a bank statement file. In case you are importing data from your previous personal + finance manager application select the appropriate option. +</para> + +<para> + In general the default QIF profile should work with your QIF data. In some + cases it might become necessary to use a modified QIF profile. See + the <link linkend="details.impexp.qifimp.profile">next section</link> for more + details on that subject. +</para> + +<para> + Click on <guibutton>Import</guibutton> to import the QIF file. +</para> + +<para> + &kappname; will start scanning the file to determine the formats used to + represent dates and numbers. In case it cannot determine a date format + unambiguously, &kappname; will ask the user to select one from the list of + possible date formats. +</para> + +<para> + Next, &kappname; imports the data and creates all necessary objects, such as + payee information, accounts and category records, and stock price information. + Wherever possible, existing transactions will be matched against the imported + information. A progress bar is shown and updated during the import process. +</para> + +<para> + In case &kappname; could not detect the name of the account to be imported, + the user will be asked to select the account into which the data should be + imported. If the account does not already exist in your file, a new account + can be created by clicking on <guibutton>Create</guibutton>. +</para> + +<para> + At the end of the import, &kappname; shows a statement import statistics + window. +</para> + +<para> +<screenshot> + <screeninfo>Statement statistics</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="qif_report.png" format="PNG" /> + </imageobject> + <textobject> + <phrase>Statement statistics</phrase> + </textobject> + </mediaobject> +</screenshot> +</para> + +<para> + After importing, all of the imported transactions will be shown with a yellow + background in the ledger view. In case &kappname; was able to match an + imported transaction with an already existing transaction, the background is + shown in light green. +</para> + +<para> + The next step is to verify the imported data and accept it. This is a general + process and also applies to imports from other sources. It is outlined in a + separate section of this document. +</para> + +<note> +<para> + The colors used to mark imported and matched transactions are customizable and + may be different in your environment. +</para> +</note> +</sect2> + +<!-- +<sect2> +<title>Accepting the imported transactions</title> +<para> + + When &kappname; has finished importing the QIF transactions the account will be shown with the imported transactions listed in Yellow. +</para> + +<para> +<screenshot> + <screeninfo>Imported transactions</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="qifimportverify.png" format="PNG" /> + </imageobject> + <textobject> + <phrase>Imported transactions</phrase> + </textobject> + </mediaobject> +</screenshot> +</para> + +<para> + Some of your transactions may be flashing red in the ledger. + This is because they need to be assigned a category. + The importer was not able to automatically assign a category based on your past transaction history. +</para> + +<para> + Transaction data can be edited or even deleted if needed. To edit a transaction simply double click on the entry or hit enter when the entry is highlighted. Once finished click on <guibutton>OK</guibutton> to accept the imported transactions or <guibutton>Cancel</guibutton> to remove the imported transactions. +</para> + +</sect2> + +<sect2><title>Importing Investments</title> + +<para> + Please note that if you are importing a file with investment transactions, those investments must first exist in your &kappname; file. + The trading symbol is used to match, so please ensure that the symbol in &kappname; is exactly the same as the one in the file you're importing. +</para> +</sect2> +--> + +<sect2 id="details.impexp.qifimp.profile"> +<title>Setting up a QIF profile</title> + +<para> + Because there is no universally standard format for a QIF file, different + vendors have taken liberties with the format, and introduced their own + nuances. The QIF Profile allows &kappname; to know about the peculiarities of + your file. To edit an existing QIF Profile, or to create a new one, press the + <quote>New</quote> button on the QIF Import dialog, near the profile selector. +</para> + +<para> + <screenshot> + <mediaobject> + <imageobject> + <imagedata fileref="qifimport-qifprofileeditor.png" format="PNG" /> + </imageobject> + <textobject> + <phrase>QIF Profile Editor</phrase> + </textobject> + </mediaobject> + </screenshot> +</para> + +<note> +<para> + Previous versions of &kappname; used to have a tab for date and amount + specifications. &kappname; now determines those settings by scanning the + file. If it cannot figure out all settings, it will interrogate the user + during import. +</para> +</note> +<!-- +<para> + The most commonly changed thing between QIF implementations is the date format. + So if this is the first time you're importing a QIF file, spend a few moments to figure out what format the dates are in, and set the QIF Profile accordingly. + See the discussion below on apostrophe format for more details. +</para> + +<para> + <screenshot> + <mediaobject> + <imageobject> + <imagedata fileref="qifimport-qifprofiledate.png" format="PNG" /> + </imageobject> + <textobject> + <phrase>QIF Profile Date</phrase> + </textobject> + </mediaobject> + </screenshot> +</para> + +</sect2> + +<sect2><title>Apostrophe format</title> + +<para> + Many common QIF writers use a 2-digit representation for the year. + This is ambiguous, because the importer cannot know which century the date belongs in. + To make things even more complicated, QIF files will often used an apostrophe as a year separator to indicate that the date belongs in the OTHER century from the default. +</para> +<para> + For example, if the default century is 1900-1999, the date 12/31/95 would mean 1995. The date 12/31'05 would mean 2005. +</para> +<para> + Because the QIF format is not standardized, it's impossible to know which century is desired. + This is why you have to explicitly state it in the QIF profile. + You do this by specifying which century is intended when an apostrophe is found. + In the example above, you would set the Apostrophe Format to "2000-2099", so dates with an apostrophe will be interpreted as being > year 2000. + In this case, dates without an apostrophe will be treated as being in the 1900's. +</para> +--> +</sect2> + +<sect2><title>Transaction matching</title> + +<para> + As noted previously, one of the major drawbacks of the QIF format is the lack + of a unique identifier for each transaction. Thus, if you import a QIF file + and some of the transactions are already in your ledger, you may get + duplicates. &kappname; attempts to get around this by looking for + transactions that look similar to those you already have. If it finds + something that looks like the same transaction, it will match the apparent + duplicate. +</para> + +<para> + This can be a problem if you have transactions that look too similar but are + actually different. In this case, you can unmatch those transactions later in + the ledger view. +</para> +</sect2> + +<sect2> +<title>Writing an import filter</title> + +<para> + Sometimes you may have data in a custom format, like comma-separated-values + (CSV), or something else unique to your situation. You can still import that + file into &kappname; using a QIF Import Filter. A filter is a custom program + you write which takes your special file as input, and produces a QIF file as + output. This can be a shell script, a perl script, a compiled program written + in C/C++, or anything else you can dream of, as long as the system can run it. +</para> + +<para> + To use it, edit your favorite QIF Profile, and select the Filter tab. Enter + the location of your filter program where prompted. Then, whenever you do a + QIF import using this profile, the file you select for importing will be run + through your filter first. +</para> + +<para> + A common problem is to convert a list of comma-separated-values into a QIF + file. This is a textbook case for the awk tool. Create a script called + csv2qif.awk, with the following two lines as contents: +</para> + +<programlisting> + BEGIN { FS=","; print "!Type:Bank" } + + { print "D"$1; print "T"$2; print "N"$3; print "P"$4; print "M"$5; print "^" } +</programlisting> + +<para> + Then, change the QIF keys (D,T,N,P,M) to match the order of your csv data. + Set the input filter to <userinput>awk -f csv2qif.awk</userinput>. +</para> + +<para> + Another problem sometimes arises in the encoding of QIF files. &kappname; + expects files to be UTF8 encoded. If your file is encoded in something else, + it can be useful to convert it to UTF8. For example to convert it from + iso-8859-1, you would set the input filter to <userinput>recode + iso-8859-1..utf-8</userinput>. +</para> + +</sect2> +<sect2> +<title>Special &kappname; QIF extensions</title> + +<para> + As already mentioned, one of the major drawbacks of the QIF format is the lack + of a unique identifier for each transaction. If you are writing your own QIF + file creator (or filter, as described above), you can overcome this problem. + &kappname; supports the '#' field. The importer will interpret this as a + unique transaction ID, and disregard the record if the transaction is already + in the system. +</para> +</sect2> +</sect1> + +<sect1 id="details.impexp.qifexp"> +<title>QIF Exporter</title> +<para> + To export one of your accounts to a QIF file, choose + the <guimenuitem>Export</guimenuitem> <guimenuitem>QIF</guimenuitem> from + the <guimenu>File</guimenu> menu. You will be prompted for which single + account to export, what file to export it to, and what QIF Profile to use. +</para> + +<note><para> + At the moment, QIF Exporter does not handle export of investments. +</para></note> + +<para> + <screenshot> + <mediaobject> + <imageobject> + <imagedata fileref="qifimport-export.png" format="PNG" /> + </imageobject> + <textobject> + <phrase>QIF Export</phrase> + </textobject> + </mediaobject> + </screenshot> +</para> +</sect1> + +<sect1 id="details.impexp.ofx"> +<sect1info> + <author> + <firstname>Ace</firstname> + <surname>Jones</surname> + <affiliation> + <address><email>acejones@users.sourceforge.net</email></address> + </affiliation> + </author> + <author> + <firstname>Thomas</firstname> + <surname>Baumgart</surname> + <affiliation> + <address><email>ipwizard@users.sourceforge.net</email></address> + </affiliation> + </author> +</sect1info> +<title>OFX Importer Plugin</title> + +<sect2> +<title>Getting the plugin</title> + +<para> + &kappname; will import OFX files painlessly. However, this functionality is + not built into the core program. You must obtain and install the OFX Importer + Plugin. Once that is installed, the command to import OFX files will + automatically show up under the <quote>File | Import</quote> menu. +</para> +<para> + Note that many prepackaged versions of &kappname; were built with the OFX + importer already included or available as a separate package. If the OFX + importer does not seem to be installed in your version, the first place to + check is in the same place you got your base &kappname; package. +</para> +<para> + If you have installed from RPM, the OFX Importer Plugin is contained within + the kmymoney-ofx RPM. It should be available from whatever source you got the + base &kappname; RPM. If you have built from sources, all you need to do is + have preferrably the libOFX 0.9 development headers and libraries installed + on your system. The &kappname; build process will detect these and compile + the plugin. libOFX 0.8.2 is supported as well, but some features are not + supported with this version of the library. +</para> +<para> + Should you run into trouble trying to compile &kappname;, and you are certain + you have the correct version of libOFX installed, please contact the + developers list &devlist; for assistance. Include a copy of your config.log + file, compressed first via gzip. +</para> +</sect2> + +<sect2> +<title>Importing an OFX file</title> + +<para> + The most basic way to import an OFX file is to choose the importer from the + menu bar. From the <guimenu>File</guimenu> menu, + choose <guimenuitem>Import</guimenuitem>, and + then <guimenuitem>OFX</guimenuitem>. If OFX does not show up under Import, + you do not have the OFX Importer Plugin installed correctly. Please see the + previous section. +</para> + +<para> + The first thing the importer will do is ask you into which account to import + the transactions. If there are transactions from multiple accounts in your + file, you will be asked this question multiple times. +</para> + +<para> + After importing, some of your transactions may be shown with an exclamation + mark on a yellow triangle in the ledger. This is because they need to be + assigned a category. The importer was not able to automatically assign a + category based on your past transaction history. You can edit each + transaction in the ledger to assign a category, and the mark will be removed. +</para> + +<para> + Please note that this section describes the <quote>native</quote> OFX + importer. OFX files may also be imported using the AqBanking Importer Plugin + if you have installed that. Note that the two importers do behave slightly + differently, and they are written and supported by two different developers. +</para> +</sect2> + +<sect2> +<title>Importing Investments</title> + +<para> + Please note that if you are importing a file with investment transactions, + those investments must first exist in your &kappname; file. The trading + symbol is used to match, so please ensure that the symbol in &kappname; is + exactly the same as the one in the file you're importing. +</para> +</sect2> + +<sect2 id="details.impexp.webconnect"> +<title>Web Connect</title> + +<para> + The easiest way to import an OFX file is to set up Web Connect. Visit your + bank's web site, and click on a link to download an OFX file. Your browser + should ask you what program you would like to use to open the program. Point + your browser to &kappname;. It will then import the downloaded OFX file into + the &kappname; file you most recently had open. You can also change the file + associations of your desktop environment, and have &kappname; open the OFX + file automatically for you. +</para> + +<para> + If you need to import the OFX file into some other &kappname; file, load up + that file in &kappname; first, and then visit your bank's web site. +</para> +</sect2> + +<sect2 id="details.impexp.ofxdirectconnect"> +<title>Direct Connect</title> + +<para> + OFX Direct Connect is now supported in &kappname;. This gives you the ability + to contact your bank directly to obtain statements. In the future, there will + be more help written, and this will be moved to its own section. +</para> + +<para> + To enable this feature, you must compile &kappname; with the + --enable-ofxbanking switch (now the default). +</para> + +<para> + Please be warned: Many banks require a separate signup, will give you a + separate password or PIN, and may even charge you a separate fee for this + service. No bank directly supports &kappname;. You will have to tell them + you want to bank directly from MS Money or Quicken. +</para> + +<para> + The first step is to configure each account for which you wish to download + statements. Go to the Accounts view, right click on the account you wish to + configure, and choose <quote>Map to online account...</quote>. In case more + than one online banking plugin is installed on your system you will be asked + which one to use. For the internal OFX method select KMyMoney OFX. A list of + banks will be downloaded from the Internet and a wizard will guide you through + choosing a bank, entering your username and password, and selecting an + account. Should you find that your bank is not listed, then it may still be + possible to use the manual option. Your bank may be able to provide the + required parameters, or you may have to do some research to find them. +</para> + +<para> + Once you have an account set up with online banking, go to the ledger for that + account. Then from the <quote>Account</quote> menu, choose <quote>Update + account...</quote>. This will connect to your bank, and download a statement + for the last 60 days. +</para> +</sect2> + +<sect2> +<title>Exporting an OFX file</title> + +<para> + It is not possible to export your data as an OFX file currently. If you are + interested to contribute in this area, please contact the libofx development + team for details. +</para> +</sect2> +</sect1> + +<sect1 id="details.impexp.plugins"> +<title>Writing Importer Plugins</title> + +<para> + &kappname; contains explicit support for importer plugins. If you have a + custom format, and you would like to write an importer plugin, we would value + your contribution. To do so, you'll need to compile the program from source. + Then use the OFX Importer Plugin as an example. +</para> +</sect1> +</chapter> |