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

 <?xml version="1.0" encoding="UTF-8"?>
 <chapter id="details.impexp">
 <chapterinfo>
   <authorgroup>
     <author> &Ace.Jones; &Ace.Jones.mail; </author>
     <author> &Jack.H.Ostroff; &Jack.H.Ostroff.mail; </author>
   </authorgroup>
   <date>2022-06-05</date>
   <releaseinfo>5.1.2</releaseinfo>
 </chapterinfo>
 
 <title>Importing and Exporting</title>
 
 <sect1 id="details.impexp.gnucash">
 <sect1info>
   <author>&Tony.Bloomfield; &Tony.Bloomfield.mail;</author>
 </sect1info>
 
 <title>&gnucash; Importer</title>
 
 <sect2>
 <title>&gnucash; Files</title>
 
 <para>
   The &kmymoney; &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 &kmymoney; 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 <menuchoice><guimenu>Actions</guimenu><guimenuitem>Check
   &amp; Repair All</guimenuitem></menuchoice> menu item of &gnucash; be run
   before attempting to import.
 </para>
 
 <para>
   Files can be opened by specifying the filename on the command line
   (<command>kmymoney &lt;path to file&gt;</command>), or by means of the &kmymoney;
   <menuchoice>
     <shortcut><keycombo>&Ctrl;<keycap>O</keycap></keycombo></shortcut>
     <guimenu>File</guimenu><guimenuitem>Open</guimenuitem>
   </menuchoice> or
   <menuchoice>
     <guimenu>File</guimenu><guisubmenu>Import</guisubmenu>
   </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 &kmymoney; 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. &kmymoney; supports 5 main types of accounts: Asset, Liability,
   Income, Expense, and Equity; each of which may have various subtypes, &eg;,
   Checking, Credit Card, &etc;  &kmymoney; includes a 'standard' account for
   each of these five types, and all other accounts are held subordinate to one
   of these. &kmymoney; 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>
   &kmymoney; uses the term Category to denote an account of an Income or Expense
   type. Unlike &gnucash;, these are not considered as 'ledger' accounts, and direct
   entry of transactions 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
   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 &kmymoney; 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>&kmymoney; type</entry>
   </row>
 </thead>
 <tbody>
   <row>
     <entry><literal>BANK</literal></entry><entry><literal>Checking</literal></entry>
   </row>
   <row>
     <entry><literal>CHECKING</literal></entry><entry><literal>Checking</literal></entry>
   </row>
   <row>
     <entry><literal>SAVINGS</literal></entry><entry><literal>Savings</literal></entry>
   </row>
   <row>
     <entry><literal>ASSET</literal></entry><entry><literal>Asset</literal></entry>
   </row>
   <row>
     <entry><literal>CASH</literal></entry><entry><literal>Cash</literal></entry>
   </row>
   <row>
     <entry><literal>CURRENCY</literal></entry><entry><literal>Cash</literal></entry>
   </row>
   <row>
     <entry><literal>MONEYMRKT</literal></entry><entry><literal>MoneyMarket</literal></entry>
   </row>
   <row>
     <entry><literal>STOCK</literal></entry><entry><literal>Stock</literal></entry>
   </row>
   <row>
     <entry><literal>MUTUAL</literal></entry><entry><literal>Stock</literal></entry>
   </row>
   <row>
     <entry><literal>EQUITY</literal></entry><entry><literal>Equity</literal></entry>
   </row>
   <row>
     <entry><literal>LIABILITY</literal></entry><entry><literal>Liability</literal></entry>
   </row>
   <row>
     <entry><literal>CREDIT</literal></entry><entry><literal>CreditCard</literal></entry>
   </row>
   <row>
     <entry><literal>INCOME</literal></entry><entry><literal>Income</literal></entry>
   </row>
   <row>
     <entry><literal>EXPENSE</literal></entry><entry><literal>Expense</literal></entry>
   </row>
   <row>
     <entry><literal>RECEIVABLE</literal></entry><entry><literal>Asset</literal></entry>
   </row>
   <row>
     <entry><literal>PAYABLE</literal></entry><entry><literal>Liability</literal></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 (&ie;,
   they must balance out to zero). &kmymoney; 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>
   &kmymoney; 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>
   &kmymoney; 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>
   &kmymoney; 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 &kmymoney;.
 </para>
 
 <sect4>
 <title>Currencies</title>
 
 <para>
   &kmymoney; has built-in support for all foreign 
   <link linkend="details.currencies">currency</link> types.  &kmymoney; 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 favor of an
   alternative.
 </para>
 
 <note><para>
   &kmymoney; 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></note>
 </sect4>
 
 <sect4 id="gncsecurities">
 <title>Securities and Investments</title>
 
 <para>
   Non-currency assets (normally stocks and bonds) are called Securities by
   &kmymoney;, and represent the main difference between the two products, in
   that &kmymoney; 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>
   User requirements and preferences determine which of these options is relevant
   in each situation, and in some cases, manual restructuring of accounts after
   import 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 perl
   package called <literal>Finance::Quote</literal>. &kmymoney;
   contain support for this package for obtaining stock quotes, and this will be
   used by default when importing data. You may however select to convert to the
   native method used by &kmymoney; 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' &kmymoney; 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 may 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 <literal>Finance::Quote</literal>,
   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>
   &kmymoney; 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>
   &kmymoney; 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
   &kmymoney;, 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 &kmymoney;</para>
   </listitem>
 
   <listitem>
     <para>&kmymoney; 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 &kmymoney;.  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>
   &kmymoney; 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 (&ie;, 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 (&ie;, 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 &kmymoney; 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 &kmymoney; developer list
   &devlist;.  Note that the traces produced by these options may contain data of
   a confidential nature, and the <guilabel>Anonymize data</guilabel> 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>&Thomas.Baumgart; &Thomas.Baumgart.mail;</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
   <application>Quicken</application> 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 &kmymoney; file open.
   Then select <menuchoice><guimenu>File</guimenu><guisubmenu>Import</guisubmenu>
   <guimenuitem>QIF...</guimenuitem> </menuchoice> menu item.
 </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>
   &kmymoney; 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>
   &kmymoney; will start scanning the file to determine the formats used to
   represent dates and numbers. In case it cannot determine a date format
   unambiguously, &kmymoney; will ask the user to select one from the list of
   possible date formats.
 </para>
 
 <para>
   Next, &kmymoney; imports the data and creates all necessary objects, such as
   Payees, Accounts, Categories, 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 &kmymoney; cannot 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 the <guibutton>Create</guibutton> button.
 </para>
 
 <para>
   At the end of the import, &kmymoney; 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 in the ledger 
   view with a yellow background.  In case &kmymoney; 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 &kmymoney; 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 &kmymoney; file.
         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.
 </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 &kmymoney; to know about the peculiarities of
   your file.  To edit an existing QIF Profile, use the various fields on the
   QIF Import dialog.  To create a new one, press the <guibutton>New</guibutton>
   button 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>
   Recent versions of &kmymoney; no longer have tabs for date and amount
   specifications. &kmymoney; 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 &quot;2000-2099&quot;, so dates with an apostrophe will be interpreted as being &gt; 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.  &kmymoney; attempts to get around this by looking for existing
   transactions that look similar to the one being imported.  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.  As of version 4.6,
   &kmymoney; includes a CSV Importer Plugin, but you can still import other
   types of files into &kmymoney; 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 <command>awk</command> tool. Create
   a script called <filename>csv2qif.awk</filename>, with the following two
   lines as contents:
 </para>
 
 <programlisting>
         BEGIN { FS=&quot;,&quot;; print &quot;!Type:Bank&quot; }
 
         { 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; }
 </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.  &kmymoney;
   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 &kmymoney; 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.
   &kmymoney; 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 <menuchoice><guimenu>File</guimenu><guisubmenu>Export</guisubmenu>
   <guimenuitem>QIF...</guimenuitem></menuchoice> menu item. You will be prompted for
   which single account to export, what file to export it to, and which 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>&Ace.Jones; &Ace.Jones.mail;</author>
   <author>&Thomas.Baumgart; &Thomas.Baumgart.mail;</author>
   <author>&Jack.H.Ostroff; &Jack.H.Ostroff.mail;</author>
 </sect1info>
 <title>OFX Importer Plugin</title>
 
 <sect2>
 <title>Getting the plugin</title>
 
 <para>
   &kmymoney; will import OFX files painlessly.  However, this functionality is
   not built into the core program - it is provided as a Plugin.  You must obtain
   and install the OFX Importer Plugin for this functionality to be available,
   Once that is done, the command to import OFX files will automatically show up
   under the <menuchoice><guimenu>File</guimenu>
   <guisubmenu>Import</guisubmenu></menuchoice> submenu.
 </para>
 
 <para>
   Note that the source of the Plugin is provided as part of the &kmymoney;
   source, and most prepackaged versions of &kmymoney; are 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 &kmymoney; package.  You can
   check whether it is installed either by trying to invoke the above submenu, or
   by invoking the <menuchoice><guimenu>Settings</guimenu>
   <guisubmenu>Configure KMyMoney...</guisubmenu></menuchoice> menu, selecting
   <guilabel>Plugins</guilabel> in the left pane, and looking for the OFX
   Importer in the list of installed Plugins.
 </para>
 
 <para>
   If you have installed from RPM, the OFX Importer Plugin is contained within
   the kmymoney-ofx package. It should be available from whatever source you got
   the base &kmymoney; package. If you have built from sources, all you need to
   do is have a recent version of the libOFX development headers and libraries
   installed on your system.  The &kmymoney; build process will detect these and
   compile the plugin.  As of September, 2021, version 0.10.3 was avialable,
   although the minimum required version for &kmymoney; is still 0.9.4.
 </para>
 
 <para>
   Should you run into trouble trying to compile &kmymoney;, 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
   <filename>config.log</filename> file, compressed first via <command>gzip</command>.
 </para>
 </sect2>
 
 <sect2>
 <title>What is OFX</title>
 
 <para>
   OFX stands for <quote>Open Financial Exchange,</quote> although in 2019, the
   OFX Consortium joined the <quote>Financial Data Exchange (FDX).</quote>
   According to the <ulink url="https://finincialdataexchange.org/">FDX web
   site</ulink> <quote>Open Financial Exchange is an open standard for
   client-server systems and cloud based APIs for exchanging financial data, and
   performing financial transactions between financial institutions, and
   financial applications.</quote> The specification defines formats for transfer
   of financial data both by file and by direct interchange.
 </para>
 
 <para>
   Although the standard is much more complete and robust than QIF, there are
   still variations, depending on the specific implementation used by any
   institution.  OFX files may have an extension of <quote>OFX</quote> or
   <quote>QFX</quote> (upper or lower case); this does not imply any particular
   difference in the content.  The specification is based on &XML;, so the files
   can be read in any text editor, but as whitespace is not relevant to the
   content itself, some implementations do not use any, making it very hard for a
   human to read.
 </para>
 
 <para>
   Another site with good information is <ulink url="https:/ofxhome.com/">OFX
   Home</ulink>.  They maintain a directory of financial institutions that
   support OFX.  This can be useful if you have problems setting up <link
   linkend="details.impexp.ofxdirectconnect">OFX direct connect.</link> They also
   have a forum for discussions about OFX issues.  However, there is a post on
   the site that it is expected to be closed down in February, 2022, if the
   current maintainer does not find someone to replace him and take over running
   the site.
 </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 <menuchoice><guimenu>File</guimenu><guisubmenu>Import</guisubmenu>
   <guimenuitem>OFX...</guimenuitem></menuchoice> menu item. If OFX does not show
   up under Import, the OFX Importer Plugin is either not installed or not
   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.  Note that when
   importing data for an investment account, purely cash transactions will be
   imported to the associated brokerage account, if one is configured.  If a
   brokerage account has not been configured (or does not have the default name)
   you may be asked to identify the account to use.
 </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
   Plugin.  OFX files may also be imported using the AqBanking Importer Plugin if
   you have installed that.  The two importers do behave slightly differently,
   and they are written and supported by 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 &kmymoney; file.  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.
 </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 file.  Point
   your browser to &kmymoney;.  It will then import the downloaded OFX file into
   the &kmymoney; file currently open, or the one you most recently had open.
   You can also change the file associations of your desktop environment, and
   have &kmymoney; open the OFX file automatically for you.
 </para>
 
 <para>
   If you need to import the OFX file into some other &kmymoney; file, load up
   that file in &kmymoney; 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 &kmymoney;.  This gives &kmymoney; the
   ability to contact your bank directly to obtain transaction.  To enable this
   feature, you must compile &kmymoney; with the
   <userinput><option>--enable-ofxbanking</option></userinput> switch.  This is
   now the default, and this feature is enabled in the version provided by most
   if not all Linux distributions, and the versions provided at the &kmymoney;
   website.
 </para>
 
 <para>
   Please be warned: some banks require a different signup from the main web
   banking access, will give you a separate password or PIN, and may even charge
   you a separate fee for this service.  No bank directly supports &kmymoney;.
   You will have to tell them you want to bank directly from <application>MS
   Money</application> or <application>Quicken</application>.
 </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 <guimenuitem>Map to online account...</guimenuitem>.  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
   <guimenuitem>&kmymoney; OFX</guimenuitem>. 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, 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>
 
 <note>
   <para>
     Setting up OFX Direct Connect can sometimes be a challenge, especially as
     the implementations at most institutions do not provide sufficient details
     in error messages.  One particular issue to note is that many institutions
     require you to change your password the first time you access it online
     using this method.  Unfortunately, at this time, the library that &kmymoney;
     uses (libofx) does not have a way to interactively change a password.  In
     some cases, it is possible to get a techincal support person at the
     institution to change the password for you.  Until we are able to expand
     this section with more detailed troubleshooting information, if you have
     trouble getting this to work for you, you can ask for help on the &kmymoney;
     developer mailing list &devlist;.
   </para>
 </note>
 
 <para>
   Once you have an account set up with online banking, go to the ledger for that
   account, and then choose the
   <menuchoice><guimenu>Account</guimenu><guimenuitem>Update
   account...</guimenuitem></menuchoice> menu item.  This will connect to your
   bank, and download available transactions.  You can use the <link
   linkend="details.accounts.edit">Edit account</link> dialog (under the
   <guilabel>Online settings</guilabel> tab, <guilabel>Import
   Details</guilabel> subtab) to indicate whether to download transactions since
   the last update, since a specified number of days ago, or since a specified
   date.
 </para>
 
 <note>
   <para>
     In versions of &kmymoney; prior to 4.6, the payee name was always taken from
     the <literal>PAYEEID</literal> field.  As of version 4.6, the payee name can
     be based on either the <literal>PAYEEID</literal>, <literal>NAME</literal>,
     or <literal>MEMO</literal> field in the OFX transaction.  You can configure
     this feature and some other OFX direct connect settings in the
     <guilabel>Edit account</guilabel> dialog mentioned just above.
   </para>
 </note>
 </sect2>
 
 <sect2>
 <title>Exporting an OFX file</title>
 
 <para>
   It is not currently possible to export your data as an OFX file.  If you are
   interested to contribute in this area, please contact the libofx development
   team for details.
 </para>
 </sect2>
 </sect1>
 
 <!-- These entities facilitate keeping the csv import/export information in
      separate files, but within this chapter. -->
 <!-- entity defined in index.docbook -->
 &details-impexp-csv;
 &details-impexp-csvexp;
 
 <!-- This entity facilitates keeping the woob (formerly weboob) import/export
      information in a separate file, but within this chapter. -->
 <!-- entity defined in index.docbook -->
 &details-impexp-woob;
 
 <sect1 id="details.impexp.plugins">
 <title>Writing Importer Plugins</title>
 
 <para>
   &kmymoney; contains explicit support for additional importer and/or exporter
   plugins.  If you would like to write a plugin to handle a custom format, 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>