Warning, /office/kmymoney/doc/details-impexp.docbook is written in an unsupported language. File is not indexed.

0001 <?xml version="1.0" encoding="UTF-8"?>
0002 <chapter id="details.impexp">
0003 <chapterinfo>
0004   <authorgroup>
0005     <author> &Ace.Jones; &Ace.Jones.mail; </author>
0006   </authorgroup>
0007   <date>2011-07-03</date>
0008   <releaseinfo>4.6</releaseinfo>
0009 </chapterinfo>
0011 <title>Importing and Exporting</title>
0013 <sect1 id="details.impexp.gnucash">
0014 <sect1info>
0015   <author>&Tony.Bloomfield; &Tony.Bloomfield.mail;</author>
0016 </sect1info>
0018 <title>&gnucash; Importer</title>
0020 <sect2>
0021 <title>&gnucash; Files</title>
0023 <para>
0024   The &kmymoney; &gnucash; importer handles direct
0025   reading of standard (&XML;) files as produced by &gnucash;
0026   versions 1.8 and 2.0. The following are not supported:
0027 </para>
0029 <itemizedlist>
0030   <listitem><para>import of database (Postgres) data</para></listitem>
0031   <listitem><para>import of 'multi-book' files</para></listitem>
0032   <listitem><para>import into an existing &kmymoney; file</para></listitem>
0033   <listitem><para>import of small-business specific features (Employees,
0034     Invoices, &etc;)</para></listitem>
0035   <listitem><para>export to &gnucash; files.</para></listitem>
0036 </itemizedlist>
0038 <para>
0039   The import will probably only work correctly if presented with a valid file.
0040   It is recommended that the <menuchoice><guimenu>Actions</guimenu><guimenuitem>Check
0041   &amp; Repair All</guimenuitem></menuchoice> menu item of &gnucash; be run
0042   before attempting to import.
0043 </para>
0045 <para>
0046   Files can be opened by specifying the filename on the command line
0047   (<command>kmymoney &lt;path to file&gt;</command>), or by means of the &kmymoney;
0048   <menuchoice>
0049     <shortcut><keycombo>&Ctrl;<keycap>O</keycap></keycombo></shortcut>
0050     <guimenu>File</guimenu><guimenuitem>Open</guimenuitem>
0051   </menuchoice> or
0052   <menuchoice>
0053     <guimenu>File</guimenu><guisubmenu>Import</guisubmenu>
0054   </menuchoice> menu items.
0055 </para>
0057 <para>
0058   The similarity between the two products means that much day-to-day data can be
0059   imported in a straightforward fashion. However, there are some areas where
0060   differences arise, and various options are provided to deal with these. The
0061   following sections will describe some of these differences; understanding them
0062   should lead to a smoother importation.
0063 </para>
0064 </sect2>
0066 <sect2>
0067 <title>Similarities, Differences, and Terminology</title>
0069 <sect3>
0070 <title>Small Business Usage</title>
0072 <para>
0073   It should be noted that &kmymoney; is a <emphasis>personal</emphasis> finance
0074   manager, and as such, does not directly support any of the business features
0075   of &gnucash;, such as tax tables, payroll, and tracking of lots. Any Accounts
0076   Payable or Receivable accounts found in a file will be imported as Liability
0077   or Asset accounts respectively.
0078 </para>
0079 </sect3>
0081 <sect3>
0082 <title>Accounts</title>
0084 <sect4>
0085 <title>Account types</title>
0087 <para>
0088   For both products, the highest level of structure in the file is the
0089   account. &kmymoney; supports 5 main types of account: Asset, Liability,
0090   Income, Expense and Equity, each of which may have various subtypes, &eg;,
0091   Checking, Credit Card, &etc;  &kmymoney; includes a 'standard' account for
0092   each of these five types, and all other accounts are held subordinate to one
0093   of these. &kmymoney; enforces more consistency (or less flexibility, depending
0094   on your point of view) between account types than does &gnucash;, and the
0095   importer will correct any inconsistencies it detects. This may result in a
0096   slightly different account structure, though this can, within reason, be
0097   amended after the import is complete.
0098 </para>
0099 </sect4>
0101 <sect4>
0102 <title>Categories</title>
0104 <para>
0105   &kmymoney; uses the term Category to denote an account of an Income or Expense
0106   type. Unlike &gnucash;, these are not considered as 'ledger' accounts, and entry
0107   of transactions folder into categories is not supported; allocations are made
0108   during transaction entry into other account types.
0109 </para>
0110 </sect4>
0112 <sect4>
0113 <title>Structure and Placeholders</title>
0115 <para>
0116   &gnucash; supports the use of Placeholder accounts. In effect, these are just
0117   read-only accounts into which no transactions can be entered, but which function
0118   in an analogous fashion to folders in a folder structure, as a holder for other
0119   accounts. Though &kmymoney; does not support this feature as such, it does
0120   provide a parent/child account relationship, so the importer simulates
0121   placeholders by creating empty accounts.
0122 </para>
0123 </sect4>
0125 <sect4>
0126 <title>Account Type map</title>
0128 <informaltable frame='all'>
0129 <tgroup cols='2' align='left' colsep='1' rowsep='1'>
0130 <thead>
0131   <row>
0132     <entry>&gnucash; type</entry><entry>&kmymoney; type</entry>
0133   </row>
0134 </thead>
0135 <tbody>
0136   <row>
0137     <entry><literal>BANK</literal></entry><entry><literal>Checking</literal></entry>
0138   </row>
0139   <row>
0140     <entry><literal>CHECKING</literal></entry><entry><literal>Checking</literal></entry>
0141   </row>
0142   <row>
0143     <entry><literal>SAVINGS</literal></entry><entry><literal>Savings</literal></entry>
0144   </row>
0145   <row>
0146     <entry><literal>ASSET</literal></entry><entry><literal>Asset</literal></entry>
0147   </row>
0148   <row>
0149     <entry><literal>CASH</literal></entry><entry><literal>Cash</literal></entry>
0150   </row>
0151   <row>
0152     <entry><literal>CURRENCY</literal></entry><entry><literal>Cash</literal></entry>
0153   </row>
0154   <row>
0155     <entry><literal>MONEYMRKT</literal></entry><entry><literal>MoneyMarket</literal></entry>
0156   </row>
0157   <row>
0158     <entry><literal>STOCK</literal></entry><entry><literal>Stock</literal></entry>
0159   </row>
0160   <row>
0161     <entry><literal>MUTUAL</literal></entry><entry><literal>Stock</literal></entry>
0162   </row>
0163   <row>
0164     <entry><literal>EQUITY</literal></entry><entry><literal>Equity</literal></entry>
0165   </row>
0166   <row>
0167     <entry><literal>LIABILITY</literal></entry><entry><literal>Liability</literal></entry>
0168   </row>
0169   <row>
0170     <entry><literal>CREDIT</literal></entry><entry><literal>CreditCard</literal></entry>
0171   </row>
0172   <row>
0173     <entry><literal>INCOME</literal></entry><entry><literal>Income</literal></entry>
0174   </row>
0175   <row>
0176     <entry><literal>EXPENSE</literal></entry><entry><literal>Expense</literal></entry>
0177   </row>
0178   <row>
0179     <entry><literal>RECEIVABLE</literal></entry><entry><literal>Asset</literal></entry>
0180   </row>
0181   <row>
0182     <entry><literal>PAYABLE</literal></entry><entry><literal>Liability</literal></entry>
0183   </row>
0184 </tbody>
0185 </tgroup>
0186 </informaltable>
0187 </sect4>
0188 </sect3>
0190 <sect3>
0191 <title>Transactions and Splits</title>
0193 <sect4>
0194 <title>Balanced transactions</title>
0196 <para>
0197   As with &gnucash;, data is entered in the form of transactions, each generally
0198   consisting of 2 or more split entries. In fact, valid &gnucash; transactions
0199   will always contain at least 2 splits, and to conform to &gnucash;'s
0200   double-entry bookkeeping standard, these must be in monetary balance (&ie;,
0201   they must balance out to zero). &kmymoney; encourages, but does not enforce,
0202   this standard, but any imported transaction which is not balanced will be
0203   marked in the ledger view as having a problem.
0204 </para>
0205 </sect4>
0207 <sect4>
0208 <title>Payees</title>
0210 <para>
0211   &kmymoney; prefers that all transactions have a Payee (a generic term that
0212   encompasses both payees and payers), and unlike &gnucash;, a list of these
0213   payees is maintained. Payee names are generated by the importer from the
0214   &gnucash; transaction's Description field.
0215 </para>
0216 </sect4>
0218 <sect4>
0219 <title>Transfers</title>
0221 <para>
0222   &kmymoney; uses the term Transfer to describe a transaction which does not
0223   involve a Category, but only transfers money between Asset and/or Liability
0224   accounts.
0225 </para>
0226 </sect4>
0228 <sect4>
0229 <title>Reconcile</title>
0231 <para>
0232   &kmymoney; provides an account reconciliation function similar to that of
0233   &gnucash;, and the corresponding transaction status will be imported.
0234 </para>
0235 </sect4>
0236 </sect3>
0238 <sect3>
0239 <title>Commodities</title>
0241 <para>
0242   &gnucash; uses the term Commodity to cover both currencies and non-currency
0243   assets. These are treated separately in &kmymoney;.
0244 </para>
0246 <sect4>
0247 <title>Currencies</title>
0249 <para>
0250   &kmymoney; has built-in support for all foreign 
0251   <link linkend="details.currencies">currency</link> types.  &kmymoney; also
0252   requires that the user specify a base currency, this being the default
0253   currency for new accounts. The importer will attempt to determine the most
0254   likely base currency, though this choice may be rejected in favor of an
0255   alternative.
0256 </para>
0258 <note><para>
0259   &kmymoney; does not currently support accounts denominated in 'defunct'
0260   currencies (except those replaced by the Euro). At present, it will be
0261   necessary to remove any such accounts from your &gnucash; file before
0262   importing. We hope to improve on this situation in a future release.
0263 </para></note>
0264 </sect4>
0266 <sect4 id="gncsecurities">
0267 <title>Securities and Investments</title>
0269 <para>
0270   Non-currency assets (normally stocks and bonds) are called Securities by
0271   &kmymoney;, and represent the main difference between the two products, in
0272   that &kmymoney; requires any account denominated in a security to be
0273   subordinate to an Investment Account. This is described in more detail in the
0274   chapter on <link linkend="details.investments">Investments</link>. Though
0275   users may have implemented such a relationship, &gnucash; imposes no defined
0276   structure on it, so the importer is unable to detect it and perform an
0277   automatic conversion. Three options are therefore made available:
0278 </para>
0280 <itemizedlist>
0281   <listitem>
0282     <para>Create a separate Investment account for each security, with the same
0283     name as the security</para>
0284   </listitem>
0286   <listitem>
0287     <para>Create a single Investment account which will act as 'parent' for all
0288     security accounts</para>
0289   </listitem>
0291   <listitem>
0292     <para>Create several Investment accounts, and assign securities to them as
0293     directed by the user.</para>
0294   </listitem>
0295 </itemizedlist>
0297 <para>
0298   It depends entirely on user requirements which of these options is relevant in
0299   each situation, and in some cases, manual restructuring of accounts after
0300   importation may be necessary.
0301 </para>
0302 </sect4>
0304 <sect4>
0305 <title>Prices and currency rates</title>
0307 <para>
0308   Security prices and currency exchange rates as displayed in the &gnucash; Price
0309   Editor will be imported. In addition, price and rate entries will be generated
0310   from all transactions involving securities and multiple currencies.
0311 </para>
0312 </sect4>
0314 <sect4 id="details.impexp.gncquotes">
0315 <title>Online Quotes</title>
0317 <para>
0318   For obtaining online price and currency rate quotations, &gnucash; uses a
0319   package called <literal>Finance::Quote</literal>. Recent versions of &kmymoney;
0320   contain support for this package for obtaining stock quotes, and this will be
0321   used by default when importing data. You may however select to convert to the
0322   native method used by &kmymoney; which is covered in more detail in
0323   <link linkend="details.investments.onlinequotes">online quotes</link>.
0324 </para>
0326 <para>
0327   If you choose to do so, the following dialog will allow selection of a
0328   'native' &kmymoney; price source, or a user-defined source, for each account
0329   for which online quotes are required. However, the stock (ticker) symbol will
0330   be imported unchanged. Since this symbol will almost certainly be different in
0331   the two packages, it will need to be manually edited after completion of the
0332   import process. Future currency rate updates will not use <literal>Finance::Quote</literal>,
0333   and will always use the native retrieval method.
0334 </para>
0336 <para>
0337         <screenshot>
0338         <mediaobject>
0339         <imageobject>
0340         <imagedata fileref="gnucash-select_price_source.png" format="PNG" />
0341         </imageobject>
0342         </mediaobject>
0343         </screenshot>
0344 </para>
0345 </sect4>
0346 </sect3>
0348 <sect3 id="gncschedules">
0349 <title>Scheduled Transactions</title>
0351 <para>
0352   &kmymoney; does not retain the separation made in &gnucash; between template
0353   transactions and their frequency of occurrence. Transaction data will be
0354   duplicated if the same template is used in different schedules, but this is
0355   not likely to be of great significance.
0356 </para>
0358 <sect4>
0359 <title>Schedule types</title>
0361 <para>
0362   &kmymoney; classifies all schedules as one of three types, Bills, Deposits, or
0363   Transfers. Since &gnucash; does not make such a distinction, the importer
0364   attempts to determine the classification from the accounts and direction of
0365   money movements. It may be that in some cases incorrect assumptions are made,
0366   and these will need manual correction.
0367 </para>
0368 </sect4>
0370 <sect4>
0371 <title>Suspect Schedules</title>
0373 <para>
0374   Some features of &gnucash; scheduled transactions are not available in
0375   &kmymoney;, so the importer tries in each case to reach a reasonable
0376   compromise in converting the data. These transactions will be flagged as
0377   suspect, and the user will be given the option of editing them directly during
0378   the import process. Examples of situations which may cause this are:
0379 </para>
0381 <itemizedlist>
0382   <listitem>
0383     <para>some frequency intervals supported in &gnucash; are not currently
0384     available in &kmymoney;</para>
0385   </listitem>
0387   <listitem>
0388     <para>&kmymoney; does not support the use of formulae and variables in
0389     amount fields</para>
0390   </listitem>
0392   <listitem>
0393     <para>complex cases which have not yet been identified for import.</para>
0394   </listitem>
0395 </itemizedlist>
0397 <para>
0398   Despite best efforts, it is possible that, due to the many options involved, a
0399   scheduled transaction may cause a fatal error within &kmymoney;.  If this sort
0400   of problem seems to be occurring, the importer offers the option to drop all
0401   suspect schedules.
0402 </para>
0403 </sect4>
0404 </sect3>
0406 <sect3>
0407 <title>Reports</title>
0409 <para>
0410   &kmymoney; provides a comprehensive selection of configurable reports,
0411   described in more detail in <link linkend="details.reports">Reports.</link>
0412   These will not necessarily, however, match precisely those reports available
0413   in &gnucash;.
0414 </para>
0415 </sect3>
0416 </sect2>
0418 <sect2>
0419 <title>Selecting Importer Options</title>
0421 <para id="details.impexp.gncoptions">
0422         <screenshot>
0423         <mediaobject>
0424         <imageobject>
0425         <imagedata fileref="gnucash-import_options.png" format="PNG" />
0426         </imageobject>
0427         </mediaobject>
0428         </screenshot>
0429 </para>
0431 <sect3>
0432 <title>Investment Handling</title>
0434 <para>
0435   See <link linkend="gncsecurities">"Securities and Investments"</link> above.
0436 </para>
0437 </sect3>
0439 <sect3>
0440 <title>Online Quotes</title>
0442 <para>
0443   Turn this off if you wish to use the native method for future online price
0445 </para>
0447 <para>
0448   See <link linkend="details.impexp.gncquotes">"Online Quotes"</link> above.
0449 </para>
0450 </sect3>
0452 <sect3>
0453 <title>Scheduled Transactions</title>
0455 <para>
0456   See <link linkend="gncschedules">"Scheduled Transactions"</link> above.
0457 </para>
0458 </sect3>
0460 <sect3>
0461 <title>Decoding Options</title>
0463 <para>
0464   If your native language is written in letters or symbols which are different
0465   from those used in the 'Latin' languages (&ie;, generally Western European),
0466   these are represented in a special fashion ('encoded') in your &gnucash; file.
0467   If these letters are not displayed correctly on your screen, then they must be
0468   decoded.  Currently, it is often not possible to detect accurately which form
0469   of decoding must be used, so you may need to set this option and select an
0470   entry from the list.  In general, the first item in the list will be that
0471   which is considered appropriate for your locale (&ie;, the country and
0472   language which was selected as native when your operating system was
0473   installed), so this should be tried first.  Since the import process does not
0474   overwrite your &gnucash; file, you are free to experiment with any of these
0475   selections.
0476 </para>
0477 </sect3>
0479 <sect3>
0480 <title>Transaction Notes option</title>
0482 <para>
0483   Under some usage conditions, non-split &gnucash; transactions may contain
0484   residual, often incorrect, memo data which is not normally visible to the
0485   user. When imported into &kmymoney; however, due to display differences, this
0486   data can become visible. Often, these transactions will have a Notes field
0487   describing the real purpose of the transaction. If this option is selected,
0488   these notes, if present, will be used to override the extraneous memo data.
0489 </para>
0490 </sect3>
0492 <sect3>
0493 <title>Debug Options</title>
0495 <para>
0496   These need only be used in the event of import problems.  If you have such
0497   problems, you should also report them to the &kmymoney; developer list
0498   &devlist;.  Note that the traces produced by these options may contain data of
0499   a confidential nature, and the <guilabel>Anonymize data</guilabel> option
0500   should be used if they are to be made publicly available.
0501 </para>
0502 </sect3>
0503 </sect2>
0505 <sect2>
0506 <title>Import Report</title>
0508 <para>
0509   At the end of processing, the importer produces a report showing the number of
0510   different entities processed, and any errors or anomalies encountered. This
0511   report will be displayed on screen, and may be saved to a file for later
0512   review. A full report may contain the following sections:
0513 </para>
0515 <itemizedlist>
0516   <listitem>
0517     <para>Record counts</para>
0518   </listitem>
0520   <listitem>
0521     <para>Inconsistencies in account types and actions taken</para>
0522   </listitem>
0524   <listitem>
0525     <para>Details of suspect schedules</para>
0526   </listitem>
0527 </itemizedlist>
0529 <para>
0530         <screenshot>
0531         <mediaobject>
0532         <imageobject>
0533         <imagedata fileref="gnucash-report.png" format="PNG" />
0534         </imageobject>
0535         </mediaobject>
0536         </screenshot>
0537 </para>
0538 </sect2>
0539 </sect1>
0541 <sect1 id="details.impexp.qifimp">
0542 <sect1info>
0543   <author>&Thomas.Baumgart; &Thomas.Baumgart.mail;</author>
0544 </sect1info>
0546 <title>QIF Importer</title>
0548 <sect2>
0549 <title>QIF format considered harmful</title>
0551 <para>
0552   Generally speaking, the QIF format should be avoided wherever possible.  It is
0553   a poor choice for transporting financial data.  Among other things, QIF suffers
0554   from these problems:
0555 </para>
0557 <itemizedlist>
0558   <listitem>
0559     <para>Lack of standardized format: Different versions of the same program
0560     will impart different meanings to the same element.</para>
0561   </listitem>
0563   <listitem>
0564     <para>Lack of transaction identifier: Because there is no ID number
0565     associated with each transaction, matching duplicate transactions is
0566     haphazard at best.</para>
0567   </listitem>
0569   <listitem>
0570     <para>Lack of expressiveness: The grammar is really simple, and cannot
0571     portray the depth of financial information found in today's financial
0572     environment.</para>
0573   </listitem>
0574 </itemizedlist>
0576 <para>
0577   This is generally why Intuit stopped supporting QIF input at all with
0578   <application>Quicken</application> 2005. If you have the option of getting
0579   data some other way, like OFX, always choose that option.
0580 </para>
0581 </sect2>
0583 <sect2>
0584 <title>How to import a QIF file</title>
0586 <para>
0587   To import a QIF file, first ensure you have a valid &kmymoney; file open.
0588   Then select <menuchoice><guimenu>File</guimenu><guisubmenu>Import</guisubmenu>
0589   <guimenuitem>QIF...</guimenuitem> </menuchoice> menu item.
0590 </para>
0592 <para>
0593         <screenshot>
0594         <mediaobject>
0595         <imageobject>
0596         <imagedata fileref="qifopen.png" format="PNG" />
0597         </imageobject>
0598         </mediaobject>
0599         </screenshot>
0600 </para>
0602 <para>
0603   The resulting dialog prompts for the QIF filename allowing you to locate the
0604   file by clicking on the <guibutton>Browse</guibutton> button.
0605 </para>
0607 <para>
0608   Also, &kmymoney; differentiates between the import of a bank statement file
0609   and historic data exported from another application. The default is to import
0610   a bank statement file. In case you are importing data from your previous personal
0611   finance manager application select the appropriate option.
0612 </para>
0614 <para>
0615   In general the default QIF profile should work with your QIF data. In some
0616   cases it might become necessary to use a modified QIF profile. See
0617   the <link linkend="details.impexp.qifimp.profile">next section</link> for more
0618   details on that subject.
0619 </para>
0621 <para>
0622   Click on <guibutton>Import</guibutton> to import the QIF file.
0623 </para>
0625 <para>
0626   &kmymoney; will start scanning the file to determine the formats used to
0627   represent dates and numbers. In case it cannot determine a date format
0628   unambiguously, &kmymoney; will ask the user to select one from the list of
0629   possible date formats.
0630 </para>
0632 <para>
0633   Next, &kmymoney; imports the data and creates all necessary objects, such as
0634   payee information, accounts and category records, and stock price information.
0635   Wherever possible, existing transactions will be matched against the imported
0636   information. A progress bar is shown and updated during the import process.
0637 </para>
0639 <para>
0640   In case &kmymoney; could not detect the name of the account to be imported,
0641   the user will be asked to select the account into which the data should be
0642   imported. If the account does not already exist in your file, a new account
0643   can be created by clicking on <guibutton>Create</guibutton>.
0644 </para>
0646 <para>
0647   At the end of the import, &kmymoney; shows a statement import statistics
0648   window.
0649 </para>
0651 <para>
0652 <screenshot>
0653         <screeninfo>Statement statistics</screeninfo>
0654         <mediaobject>
0655         <imageobject>
0656         <imagedata fileref="qif_report.png" format="PNG" />
0657         </imageobject>
0658         <textobject>
0659         <phrase>Statement statistics</phrase>
0660         </textobject>
0661         </mediaobject>
0662 </screenshot>
0663 </para>
0665 <para>
0666   After importing, all of the imported transactions will be shown with a yellow
0667   background in the ledger view.  In case &kmymoney; was able to match an
0668   imported transaction with an already existing transaction, the background is
0669   shown in light green.
0670 </para>
0672 <para>
0673   The next step is to verify the imported data and accept it. This is a general
0674   process and also applies to imports from other sources. It is outlined in a
0675   separate section of this document.
0676 </para>
0678 <note>
0679 <para>
0680   The colors used to mark imported and matched transactions are customizable and
0681   may be different in your environment.
0682 </para>
0683 </note>
0684 </sect2>
0686 <!--
0687 <sect2>
0688 <title>Accepting the imported transactions</title>
0689 <para>
0691         When &kmymoney; has finished importing the QIF transactions the account will be shown with the imported transactions listed in Yellow.
0692 </para>
0694 <para>
0695 <screenshot>
0696         <screeninfo>Imported transactions</screeninfo>
0697         <mediaobject>
0698         <imageobject>
0699         <imagedata fileref="qifimportverify.png" format="PNG" />
0700         </imageobject>
0701         <textobject>
0702         <phrase>Imported transactions</phrase>
0703         </textobject>
0704         </mediaobject>
0705 </screenshot>
0706 </para>
0708 <para>
0709         Some of your transactions may be flashing red in the ledger.  
0710         This is because they need to be assigned a category.  
0711         The importer was not able to automatically assign a category based on your past transaction history.
0712 </para>
0714 <para>  
0715         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.
0716 </para>
0718 </sect2>
0720 <sect2><title>Importing Investments</title>
0722 <para>
0723         Please note that if you are importing a file with investment transactions, those investments must first exist in your &kmymoney; file.
0724         The trading symbol is used to match, so please ensure that the symbol in &kmymoney; is exactly the same as the one in the file you're importing.
0725 </para>
0726 </sect2>
0727 -->
0729 <sect2 id="details.impexp.qifimp.profile">
0730 <title>Setting up a QIF profile</title>
0732 <para>
0733   Because there is no universally standard format for a QIF file, different
0734   vendors have taken liberties with the format, and introduced their own
0735   nuances.  The QIF Profile allows &kmymoney; to know about the peculiarities of
0736   your file.  To edit an existing QIF Profile, or to create a new one, press the
0737   <guibutton>New</guibutton> button on the QIF Import dialog, near the profile selector.
0738 </para>
0740 <para>
0741         <screenshot>
0742         <mediaobject>
0743         <imageobject>
0744         <imagedata fileref="qifimport-qifprofileeditor.png" format="PNG" />
0745         </imageobject>
0746         <textobject>
0747         <phrase>QIF Profile Editor</phrase>
0748         </textobject>
0749         </mediaobject>
0750         </screenshot>
0751 </para>
0753 <note>
0754 <para>
0755   Previous versions of &kmymoney; used to have a tab for date and amount
0756   specifications. &kmymoney; now determines those settings by scanning the
0757   file. If it cannot figure out all settings, it will interrogate the user
0758   during import.
0759 </para>
0760 </note>
0761 <!--
0762 <para>
0763         The most commonly changed thing between QIF implementations is the date format.  
0764         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.  
0765         See the discussion below on apostrophe format for more details.
0766 </para>
0768 <para>
0769         <screenshot>
0770         <mediaobject>
0771         <imageobject>
0772         <imagedata fileref="qifimport-qifprofiledate.png" format="PNG" />
0773         </imageobject>
0774         <textobject>
0775         <phrase>QIF Profile Date</phrase>
0776         </textobject>
0777         </mediaobject>
0778         </screenshot>
0779 </para>
0781 </sect2>
0783 <sect2><title>Apostrophe format</title>
0785 <para>
0786         Many common QIF writers use a 2-digit representation for the year. 
0787         This is ambiguous, because the importer cannot know which century the date belongs in.
0788         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.
0789 </para>
0790 <para>
0791         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.
0792 </para>
0793 <para>
0794         Because the QIF format is not standardized, it's impossible to know which century is desired.
0795         This is why you have to explicitly state it in the QIF profile.
0796         You do this by specifying which century is intended when an apostrophe is found.
0797         In the example above, you would set the Apostrophe Format to &quot;2000-2099&quot;, so dates with an apostrophe will be interpreted as being &gt; year 2000.
0798         In this case, dates without an apostrophe will be treated as being in the 1900's.
0799 </para>
0800 -->
0801 </sect2>
0803 <sect2><title>Transaction matching</title>
0805 <para>
0806   As noted previously, one of the major drawbacks of the QIF format is the lack
0807   of a unique identifier for each transaction.  Thus, if you import a QIF file
0808   and some of the transactions are already in your ledger, you may get
0809   duplicates.  &kmymoney; attempts to get around this by looking for
0810   transactions that look similar to those you already have.  If it finds
0811   something that looks like the same transaction, it will match the apparent
0812   duplicate.
0813 </para>
0815 <para>
0816   This can be a problem if you have transactions that look too similar but are
0817   actually different.  In this case, you can unmatch those transactions later in
0818   the ledger view.
0819 </para>
0820 </sect2>
0822 <sect2>
0823 <title>Writing an import filter</title>
0825 <para>
0826   Sometimes you may have data in a custom format, like comma-separated-values
0827   (CSV) or something else unique to your situation.  As of version 4.6,
0828   &kmymoney; includes a CSV Importer Plugin, but you can still import other
0829   types of files into &kmymoney; using a QIF Import Filter.  A filter is a
0830   custom program you write which takes your special file as input, and produces
0831   a QIF file as output.  This can be a shell script, a perl script, a compiled
0832   program written in C/C++, or anything else you can dream of, as long as the
0833   system can run it.
0834 </para>
0836 <para>
0837   To use it, edit your favorite QIF Profile, and select the Filter tab.  Enter
0838   the location of your filter program where prompted.  Then, whenever you do a
0839   QIF import using this profile, the file you select for importing will be run
0840   through your filter first.
0841 </para>
0843 <para>
0844   A common problem is to convert a list of comma-separated-values into a QIF
0845   file. This is a textbook case for the <command>awk</command> tool. Create
0846   a script called <filename>csv2qif.awk</filename>, with the following two
0847   lines as contents:
0848 </para>
0850 <programlisting>
0851         BEGIN { FS=&quot;,&quot;; print &quot;!Type:Bank&quot; }
0853         { print &quot;D&quot;$1; print &quot;T&quot;$2; print &quot;N&quot;$3; print &quot;P&quot;$4; print &quot;M&quot;$5; print &quot;^&quot; }
0854 </programlisting>
0856 <para>
0857   Then, change the QIF keys (D,T,N,P,M) to match the order of your CSV data.
0858   Set the input filter to <userinput>awk -f csv2qif.awk</userinput>.
0859 </para>
0861 <para>
0862   Another problem sometimes arises in the encoding of QIF files.  &kmymoney;
0863   expects files to be UTF8 encoded.  If your file is encoded in something else,
0864   it can be useful to convert it to UTF8.  For example to convert it from
0865   iso-8859-1, you would set the input filter to <userinput>recode
0866   iso-8859-1..utf-8</userinput>.
0867 </para>
0869 </sect2>
0870 <sect2>
0871 <title>Special &kmymoney; QIF extensions</title>
0873 <para>
0874   As already mentioned, one of the major drawbacks of the QIF format is the lack
0875   of a unique identifier for each transaction.  If you are writing your own QIF
0876   file creator (or filter, as described above), you can overcome this problem.
0877   &kmymoney; supports the '#' field.  The importer will interpret this as a
0878   unique transaction ID, and disregard the record if the transaction is already
0879   in the system.
0880 </para>
0881 </sect2>
0882 </sect1>
0884 <sect1 id="details.impexp.qifexp">
0885 <title>QIF Exporter</title>
0886 <para>
0887   To export one of your accounts to a QIF file, choose
0888   the <menuchoice><guimenu>File</guimenu><guisubmenu>Export</guisubmenu>
0889   <guimenuitem>QIF...</guimenuitem></menuchoice> menu item. You will be prompted for
0890   which single account to export, what file to export it to, and what QIF Profile
0891   to use.
0892 </para>
0894 <note><para>
0895   At the moment, QIF Exporter does not handle export of investments.
0896 </para></note>
0898 <para>
0899         <screenshot>
0900         <mediaobject>
0901         <imageobject>
0902         <imagedata fileref="qifimport-export.png" format="PNG" />
0903         </imageobject>
0904         <textobject>
0905         <phrase>QIF Export</phrase>
0906         </textobject>
0907         </mediaobject>
0908         </screenshot>
0909 </para>
0910 </sect1>
0912 <sect1 id="details.impexp.ofx">
0913 <sect1info>
0914   <author>&Ace.Jones; &Ace.Jones.mail;</author>
0915   <author>&Thomas.Baumgart; &Thomas.Baumgart.mail;</author>
0916 </sect1info>
0917 <title>OFX Importer Plugin</title>
0919 <sect2>
0920 <title>Getting the plugin</title>
0922 <para>
0923   &kmymoney; will import OFX files painlessly.  However, this functionality is
0924   not built into the core program.  You must obtain and install the OFX Importer
0925   Plugin.  Once that is installed, the command to import OFX files will
0926   automatically show up under the <menuchoice><guimenu>File</guimenu>
0927   <guisubmenu>Import</guisubmenu></menuchoice> submenu.
0928 </para>
0930 <para>
0931   Note that many prepackaged versions of &kmymoney; were built with the OFX
0932   importer already included or available as a separate package.  If the OFX
0933   importer does not seem to be installed in your version, the first place to
0934   check is in the same place you got your base &kmymoney; package.
0935 </para>
0937 <para>
0938   If you have installed from RPM, the OFX Importer Plugin is contained within
0939   the kmymoney-ofx package. It should be available from whatever source you got the
0940   base &kmymoney; package. If you have built from sources, all you need to do is
0941   have preferably the libOFX 0.9 development headers and libraries installed on
0942   your system.  The &kmymoney; build process will detect these and compile the
0943   plugin.  At the time of release of &kmymoney; 4.6, the latest libofx version
0944   was 0.9.4, which is also the minimum required version.
0945 </para>
0947 <para>
0948   Should you run into trouble trying to compile &kmymoney;, and you are certain
0949   you have the correct version of libOFX installed, please contact the
0950   developers list &devlist; for assistance. Include a copy of your
0951   <filename>config.log</filename> file, compressed first via <command>gzip</command>.
0952 </para>
0953 </sect2>
0955 <sect2>
0956 <title>What is OFX</title>
0958 <para>
0959   OFX stands for <quote>Open Financial Exchange</quote>.  According to the
0960   <ulink url="https://www.ofx.net/">OFX web site</ulink> <quote>Open Financial
0961   Exchange (OFX) is a unified specification for the electronic exchange of
0962   financial data between financial institutions, businesses and consumers via
0963   the Internet. OFX is not a financial institution.</quote> The specification
0964   defines formats for transfer of financial data both by file and by direct
0965   interchange.
0966 </para>
0968 <para>
0969   Although the standard is much more complete and robust than QIF, there are
0970   still variations, depending on the specific implementation used by any
0971   institution.  OFX files may have an extension of <quote>OFX</quote> or
0972   <quote>QFX</quote> (upper or lower case); this does not imply any particular
0973   difference in the content.  The specification is based on &XML;, so the files
0974   can be read in any text editor, but as whitespace is not relevant to the
0975   content itself, some implementations do not use any, making it very hard for a
0976   human to read.
0977 </para>
0979 <para>
0980   Another site with good information is <ulink url="https:/ofxhome.com/">OFX
0981   Home</ulink>.  They maintain a directory of financial institutions that
0982   support OFX.  This can be useful if you have problems setting up <link
0983   linkend="details.impexp.ofxdirectconnect">OFX direct connect.</link> They also
0984   have a forum for discussions about OFX issues.
0985 </para>
0986 </sect2>
0988 <sect2>
0989 <title>Importing an OFX file</title>
0991 <para>
0992   The most basic way to import an OFX file is to choose the importer from the
0993   menu bar. From the <menuchoice><guimenu>File</guimenu><guisubmenu>Import</guisubmenu>
0994   <guimenuitem>OFX...</guimenuitem></menuchoice> menu item. If OFX does not show
0995   up under Import, you do not have the OFX Importer Plugin installed correctly.
0996   Please see the previous section.
0997 </para>
0999 <para>
1000   The first thing the importer will do is ask you into which account to import
1001   the transactions.  If there are transactions from multiple accounts in your
1002   file, you will be asked this question multiple times.
1003 </para>
1005 <para>
1006   After importing, some of your transactions may be shown with an exclamation
1007   mark on a yellow triangle in the ledger.  This is because they need to be
1008   assigned a category.  The importer was not able to automatically assign a
1009   category based on your past transaction history.  You can edit each
1010   transaction in the ledger to assign a category, and the mark will be removed.
1011 </para>
1013 <para>
1014   Please note that this section describes the <quote>native</quote> OFX
1015   importer.  OFX files may also be imported using the AqBanking Importer Plugin
1016   if you have installed that.  Note that the two importers do behave slightly
1017   differently, and they are written and supported by two different developers.
1018 </para>
1019 </sect2>
1021 <sect2>
1022 <title>Importing Investments</title>
1024 <para>
1025   Please note that if you are importing a file with investment transactions,
1026   those investments must first exist in your &kmymoney; file.  The trading
1027   symbol is used to match, so please ensure that the symbol in &kmymoney; is
1028   exactly the same as the one in the file you're importing.
1029 </para>
1030 </sect2>
1032 <sect2 id="details.impexp.webconnect">
1033 <title>Web Connect</title>
1035 <para>
1036   The easiest way to import an OFX file is to set up Web Connect.  Visit your
1037   bank's web site, and click on a link to download an OFX file.  Your browser
1038   should ask you what program you would like to use to open the file.  Point
1039   your browser to &kmymoney;.  It will then import the downloaded OFX file into
1040   the &kmymoney; file you most recently had open.  You can also change the file
1041   associations of your desktop environment, and have &kmymoney; open the OFX
1042   file automatically for you.
1043 </para>
1045 <para>
1046   If you need to import the OFX file into some other &kmymoney; file, load up
1047   that file in &kmymoney; first, and then visit your bank's web site.
1048 </para>
1049 </sect2>
1051 <sect2 id="details.impexp.ofxdirectconnect">
1052 <title>Direct Connect</title>
1054 <para>
1055   OFX Direct Connect is now supported in &kmymoney;.  This gives you the ability
1056   to contact your bank directly to obtain statements.  In the future, there will
1057   be more help written, and this will be moved to its own section.
1058 </para>
1060 <para>
1061   To enable this feature, you must compile &kmymoney; with the
1062   <userinput><option>--enable-ofxbanking</option></userinput> switch (now the default).
1063 </para>
1065 <para>
1066   Please be warned: Many banks require a separate signup, will give you a
1067   separate password or PIN, and may even charge you a separate fee for this
1068   service.  No bank directly supports &kmymoney;.  You will have to tell them
1069   you want to bank directly from <application>MS Money</application> or
1070   <application>Quicken</application>.
1071 </para>
1073 <para>
1074   The first step is to configure each account for which you wish to download
1075   statements. Go to the Accounts view, right click on the account you wish to
1076   configure, and choose <guimenuitem>Map to online account...</guimenuitem>. 
1077   In case more than one online banking plugin is installed on your system
1078   you will be asked which one to use. For the internal OFX method select
1079   <guimenuitem>&kmymoney; OFX</guimenuitem>. A list of banks will be downloaded
1080   from the Internet and a wizard will guide you through choosing a bank,
1081   entering your username and password, and selecting an account.  Should you
1082   find that your bank is not listed, then it may still be possible to use the
1083   manual option. Your bank may be able to provide the required parameters, or
1084   you may have to do some research to find them.
1085 </para>
1087 <note>
1088   <para>
1089     Setting up OFX Direct Connect can sometimes be a challenge, especially as
1090     the implementation at most institutions do not provide sufficient details in
1091     error messages.  One particular issue to note is that many institutions
1092     require you to change your password the first time you access it online
1093     using this method.  Unfortunately, at this time, the library that &kmymoney;
1094     uses (libofx) does not have a way to interactively change a password.  In
1095     some cases, it is possible to get a technical support person at the
1096     institution to change the password for you.  Until we are able to expand
1097     this section with more detailed troubleshooting information, if you have
1098     trouble getting this to work for you, you can ask for help on the &kmymoney;
1099     developer list &devlist;.
1100   </para>
1101 </note>
1103 <para>
1104   Once you have an account set up with online banking, go to the ledger for that
1105   account. Then choose <menuchoice><guimenu>Account</guimenu><guimenuitem>Update
1106   account...</guimenuitem></menuchoice> menu item. This will connect to your bank,
1107   and download a statement for the last 60 days.
1108 </para>
1110 <note>
1111   <para>
1112     In version of &kmymoney; prior to 4.6, the payee name was always taken from the
1113     <literal>PAYEEID</literal> field. As of version 4.6, the payee name can be based
1114     on either the <literal>PAYEEID</literal>, <literal>NAME</literal>, or
1115     <literal>MEMO</literal> field in the OFX transaction. You can configure this
1116     feature and some other OFX direct connect settings by selecting the appropriate
1117     tab in the <link linkend="details.accounts.edit">Edit account</link> dialog.
1118   </para>
1119 </note>
1120 </sect2>
1122 <sect2>
1123 <title>Exporting an OFX file</title>
1125 <para>
1126   It is not possible to export your data as an OFX file currently.  If you are
1127   interested to contribute in this area, please contact the libofx development
1128   team for details.
1129 </para>
1130 </sect2>
1131 </sect1>
1133 <!-- here goes the new csv impexp section.  New entity is only a temporary 
1134      workaround, although might be good to keep it in a separate file -->
1135 <!-- entity defined in index.docbook -->
1136 &details-impexp-csv;
1137 &details-impexp-csvexp;
1139 <!-- here goes the new Woob impexp section.  New entity is only a temporary
1140      workaround, although might be good to keep it in a separate file -->
1141 <!-- entity defined in index.docbook -->
1142 &details-impexp-woob;
1144 <sect1 id="details.impexp.plugins">
1145 <title>Writing Importer Plugins</title>
1147 <para>
1148   &kmymoney; contains explicit support for importer plugins.  If you have a
1149   custom format, and you would like to write an importer plugin, we would value
1150   your contribution.  To do so, you'll need to compile the program from source.
1151   Then use the OFX Importer Plugin as an example.
1152 </para>
1153 </sect1>
1154 </chapter>