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

0001 <sect1 id="details.impexp.csv">
0002 <sect1info>
0003    <author> &Allan.Anderson; &Allan.Anderson.mail; </author>
0004 </sect1info>
0005 <title>CSV Importer Plugin</title>
0007 <sect2>
0008 <title>Reasons for importing CSV Files</title>
0010 <para>
0011   In general, it is preferable to import OFX.  However, not all institutions
0012   provide data in that format.  CSV (comma separated value) files are almost
0013   always available, sometimes described as Excel or spreadsheet files.  Also,
0014   they can often be created fairly easily by capturing the data you want to
0015   import, such as in a text file, and manually editing it.
0016 </para>
0018 <para>
0019   The primary focus of the plugin is on importing data from bank statements, but
0020   there is also a capability to import some investment statements.  This plugin
0021   was initially created, before becoming a CSV importer, to produce QIF files
0022   from CSV, which could then be imported.  This functionality is still present,
0023   but is likely to be removed, as the plugin now focuses on directly importing
0024   CSV files.  Also, &kmymoney; has the native ability to <link
0025   linkend="details.impexp.qifexp">export QIF files</link>, so there is no real
0026   reason to produce a QIF file from a CSV file.
0027 </para>
0028 </sect2>
0030 <sect2>
0031 <title>Getting the plugin</title>
0033 <para>
0034   &kmymoney; will import CSV files.  This functionality is provided as a plugin,
0035   and it is now built into the core program, both in distro packages and in the
0036   source files.  Once the distro package is installed, or the source files are
0037   compiled and installed, the menu choice to import CSV files will automatically
0038   show up under the
0039   <menuchoice><guimenu>File</guimenu><guisubmenu>Import</guisubmenu></menuchoice>
0040   submenu.
0041 </para>
0043 <para>
0044   The CSV importer plugin is much newer than the OFX plugin, but most
0045   distributions are now built with the CSV importer already included or
0046   available as a separate package.  Ensure that it is enabled within &kmymoney;.
0047   Check the <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure
0048   &kmymoney;...</guimenuitem><guimenuitem>Plugins</guimenuitem></menuchoice> menu item.
0049   If the CSV importer does not seem to be installed in your version, the first
0050   place to check is in the same place you got your base &kmymoney; package. See
0051   if a later version is available, or if the importer is available as a separate
0052   package.
0053 </para>
0055 <para> 
0056   If you have installed from RPM or Deb, the CSV Importer Plugin should be
0057   contained within the kmymoney package. If you have built from source, there
0058   should be no additional requirements. The &kmymoney; build process should
0059   detect the plugin source and compile the plugin.
0060 </para>
0061 </sect2>
0063 <sect2>
0064 <title>Importing a CSV file</title>
0066 <para>
0067   To import a CSV file, choose the importer from the menu bar:
0068   <menuchoice><guimenu>File</guimenu><guisubmenu>Import</guisubmenu> <guimenuitem>CSV...</guimenuitem></menuchoice>.
0069   If CSV does not show up under Import, you do not have the CSV Importer Plugin
0070   installed correctly.  Please see the previous section.
0071 </para>
0073 <para>
0074   The CSV Importer is in the form of a wizard, with a separate page for each
0075   individual step of the process.  There may be some minor differences between
0076   the text in this handbook, the labels in the screenshots, and the labels you
0077   actually see in the wizard.  In such cases, the handbook describes what the
0078   wizard will look like in the next release.
0079 </para>
0081 <sect3>
0082 <title>CSV Import Wizard: Start</title>
0084 <para>
0085   When started, the CSV Importer displays the <guilabel>Start</guilabel>
0086   page.  The upper area, where data will be displayed, is initially empty.
0087   Below that, on the left, is a list of the steps of the import process, with
0088   the current one highlighted.  To the right of that are some brief instructions
0089   and two radio buttons, allowing the choice of either
0090   <guilabel>Banking</guilabel> or <guilabel>Investment</guilabel>.  Next there is
0091   a profile selector box, which is enabled once one of the radio buttons has
0092   been selected.  At the bottom of the display are buttons to move on to the
0093   next step of the wizard, go <guibutton>Back</guibutton> to the previous step,
0094   or <guibutton>Cancel</guibutton> the import.  At the initial step, there is
0095   also a button <guilabel>Select File</guilabel> to initially select the file to
0096   import.
0097 </para>
0098 <!-- want to use inlinemediaobject to avoid lines above and below. -->
0099   <screenshot>
0100   <mediaobject>
0101   <imageobject>
0102   <imagedata fileref="csvImporter_1.png" format="PNG" />
0103   </imageobject>
0104   </mediaobject>
0105   </screenshot>
0107 <para>
0108   Also, note the <guilabel>Skip setup</guilabel> checkbox next to the profile
0109   selector.  Initially, you should not select this check-box.  Once you have set
0110   up a profile and finished the wizard, those parameters are saved in the
0111   resource file.  Next time you use that same profile, the parameters will be
0112   loaded into the UI (User Interface).  The wizard would then plod through the
0113   following pages of parameters that you won't need to change.  So, instead,
0114   once you are happy with a profile, it may be helpful to check this box.  The
0115   wizard will then move directly to the final page, and, assuming no problems
0116   are found, you just have to click <guilabel>Import</guilabel>.
0117 </para>
0119 <para>
0120   First select either <guilabel>Banking</guilabel> or
0121   <guilabel>Investment</guilabel>, then click in the selector box, which displays
0122   "Add New Profile."  If you have previously created any profiles, you can
0123   select one of them, otherwise enter a new profile name, possibly the name of
0124   the account into which you wish to import.  If you enter a new profile name,
0125   hit &Enter; to create it.  Then, click on <guilabel>Select File</guilabel>,
0126   and a standard file selector box will open, from which you should select the
0127   CSV file you wish to import.
0128 </para>
0129 </sect3>
0131 <sect3>
0132 <title>CSV Import Wizard: Separators</title>
0133 <para>
0134   The wizard will now have advanced to the <guilabel>Separators</guilabel> page,
0135   and you should now see your data.
0136 </para>
0138   <screenshot>
0139   <mediaobject>
0140   <imageobject>
0141   <imagedata fileref="csvImporter_2.png" format="PNG" />
0142   </imageobject>
0143   </mediaobject>
0144   </screenshot>
0146   <warning>
0147     <para>
0148       It may appear that the displayed entries in the upper section of the
0149       plugin window may be edited, and in fact they may, but any edits are not
0150       kept.  The table is purely for display, not for editing.  The input file
0151       is never altered by the plugin, and the data actually imported comes from
0152       the input file, not from the display.  The one exception to this is
0153       covered in <link linkend="details.impexp.csv.secsym">Securities and
0154       Symbols</link> below.
0155     </para> 
0156   </warning>
0158 <para>
0159   The plugin should have detected the appropriate <guilabel>Field
0160   Separator</guilabel> to use, and it is not usually possible to select a
0161   different one.  In fact, attempting to do so will reset any field choices you
0162   may already have made.  There is also a selector for the <guilabel>Text
0163   Delimiter</guilabel>, but generally the quote (") is correct.  Now click on
0164   the <guibutton>Next</guibutton> button. Depending upon the earlier selection
0165   you made, you will now be on either the Banking page or the Investment page.
0166 </para>
0167 </sect3>
0169 <sect3>
0170 <title>CSV Import Wizard: Banking</title>
0171 <para>
0172   On this page, you select the column numbers from which to import the relevant fields.
0173 </para>
0175   <screenshot>
0176   <mediaobject>
0177   <imageobject>
0178   <imagedata fileref="csvImporter_3.png" format="PNG" />
0179   </imageobject>
0180   </mediaobject>
0181   </screenshot>
0183 <para>
0184   For most fields, you just need to use the appropriate dropdown to select the
0185   appropriate column.  However, there are a few special considerations.
0186 </para>
0188 <itemizedlist>
0189 <listitem>
0190 <para>
0191   In the center are two radio buttons. If your file has a single column for all
0192   values, select <guilabel>Amount</guilabel> column. However, if there are separate
0193   columns for debits and credits, select <guilabel>Debit/credit</guilabel> column.
0194   This will enable either the <guilabel>Amount</guilabel> column selector or the
0195   <guilabel>Debit</guilabel> and <guilabel>Credit</guilabel> column selectors.
0196 </para>
0197 </listitem>
0199 <listitem>
0200 <para>
0201   It is possible to select more than one column for the Memo field, by
0202   consecutive selections.  Memo columns already selected are marked in the
0203   drop-down with an asterisk (*).  If you select multiple columns in this way,
0204   their contents will be concatenated in the Memo field.
0205 </para>
0206 </listitem>
0208 <listitem>
0209 <para>
0210   If you attempt to choose the same column number for two fields, the plugin
0211   will alert you and clear both selections.  However, it is possible, if
0212   desired, to use the same column in both the
0213   <guilabel>Payee/Description</guilabel> and <guilabel>Memo</guilabel> fields.
0214   If you select a column for the <guilabel>Payee/Description</guilabel> field,
0215   and then select the same field for the <guilabel>Memo</guilabel> field, you
0216   will receive a warning that duplicate columns have been selected, but asking
0217   if you wish to proceed.  If you do, click <guibutton>Yes</guibutton>.
0218 </para>
0219 </listitem>
0221 <listitem>
0222 <para>
0223   One particular reason to also capture the Payee/Descriptor field in the Memo
0224   field is that the incoming Payee/Description field might get completely
0225   changed on import when &kmymoney; does transaction matching.  Selecting that
0226   field also as Memo will preserve that data, which would otherwise get lost.
0227 </para>
0228 </listitem>
0229 </itemizedlist>
0231 <para>
0232   If you notice you have made an incorrect choice, just change that selection.
0233   If several changes need to be made, click the
0234   <guilabel>Clear</guilabel> button. 
0235 </para>
0237 <para>
0238   Once columns have been chosen for all the necessary fields, the
0239   <guilabel>Next</guilabel> button will be enabled, and clicking it will advance
0240   the wizard.
0241 </para>
0242 </sect3>
0244 <sect3>
0245 <title>CSV Import Wizard: Investment</title>
0246 <para>
0247   This page is similar to the <guilabel>Banking</guilabel> page, although it
0248   is somewhat more complex.  Most selections are fairly obvious, but there are
0249   some items which can seem confusing until you have completed the process
0250   once or twice.
0252   <screenshot>
0253   <mediaobject>
0254   <imageobject>
0255   <imagedata fileref="csvImporter_4.png" format="PNG" />
0256   </imageobject>
0257   </mediaobject>
0258   </screenshot>
0259 </para>
0261 <para>
0262 <itemizedlist>
0263 <listitem>
0264 <para>
0265   As on the <guilabel>Banking</guilabel> page, you may select more than one
0266   column for the Memo field
0267 </para>
0268 </listitem>
0270 <listitem>
0271 <para>
0272   The <guilabel>Type/Action</guilabel> selector is to identify the column which
0273   contains the action type, such as Buy, Sell, Dividend, &etc;
0274 </para>
0275 </listitem>
0277 <listitem>
0278 <para>
0279   The <guilabel>Price Fraction</guilabel> selector is to indicate the
0280   fraction/multiplier for compatibility between imported and stored prices.  For
0281   instance, if the import file price is in cents, but your &kmymoney; account is
0282   priced in dollars, select 0.01.  Or, if your &kmymoney; data file pricing is
0283   in dollars, and so is the CSV file being imported, then set <guilabel>Price
0284   Fraction</guilabel> to 1.0.
0285 </para>
0286 </listitem>
0288 <listitem>
0289 <para>
0290   Use the <guilabel>Fee Column</guilabel> selector if your file has a distinct
0291   column for fees.  Beware, though, that the fee might have been taken into
0292   account in the price.  If there is a fee, and it is a percentage figure,
0293   rather than a value, click the <guilabel>Fee is percentage</guilabel> check
0294   box.  Note that on this page, this is the only field to explicitly include
0295   "column" in the label, to emphasize that it is for the fee column, not for any
0296   actual fee.
0297 </para>
0298 </listitem>
0300 <listitem>
0301 <para>
0302   Below the column selectors are two areas for the security identity.  Depending
0303   upon your broker or financial institution, your file may contain entries for
0304   only one or for several securities.
0306   <itemizedlist>
0307   <listitem>
0308   <para>
0309   If the file contains transactions for just a single security, with the name
0310   possibly in a header row, the name should be entered into the
0311   <guilabel>Security Name</guilabel> box. The name you enter will be added to
0312   the drop-down list for future use. You may subsequently wish to remove that
0313   name from the list.  If so, select it, then click the <guilabel>Hide
0314   security</guilabel> button.  This removes it only from this list, and has no
0315   effect on your main &kmymoney; file.
0316   </para>
0317   </listitem>
0319   <listitem>
0320   <para>
0321   If the file includes transactions for several securities, each will be
0322   identified by its ticker symbol in a column with further detail in another
0323   column. Select those columns in the <guilabel>Symbol</guilabel> and
0324   <guilabel>Detail</guilabel> selectors.  It may be that a security has no
0325   official symbol, and in this case a pseudo-symbol may be invented; this is not
0326   a problem, as long as it uniquely identifies that security in the import file.
0327   Sometimes the actual activity type is embedded in the detail column, possibly
0328   prefixed by a standard text. For instance, if the field contains <quote>type:
0329   dividend</quote>, go to <guilabel>Filter</guilabel> text box and enter
0330   <quote>type: </quote> including the trailing space.
0331   </para>
0332   </listitem>
0333   </itemizedlist>
0334 </para>
0335 </listitem>
0336 </itemizedlist>
0337 </para>
0339 <para>
0340   When all required fields are selected,
0341   the <guilabel>Next</guilabel> button will be enabled, and clicking it will
0342   advance the wizard.
0343 </para>
0344 </sect3>
0346 <sect3>
0347 <title>CSV Import Wizard: Lines</title>
0348 <para>
0349   On this page, you indicate if any lines should be ignored at the beginning or
0350   end of the file.  You also indicate the format of any date column.
0352   <screenshot>
0353   <mediaobject>
0354   <imageobject>
0355   <imagedata fileref="csvImporter_5.png" format="PNG" />
0356   </imageobject>
0357   </mediaobject>
0358   </screenshot>
0359 </para>
0361 <formalpara><title>Start line</title>
0362 <para>
0363   Set this so the importer skips any header lines in the file.  Your choice will
0364   be saved in this profile for future use. The start and end lines interact, and
0365   the start line may not be higher than the end line. If the <guilabel>Start
0366   line</guilabel> selector does not respond, check the end line setting.
0367 </para>
0368 </formalpara>
0370 <formalpara><title>End line</title>
0371 <para>
0372   The importer will automatically set this to the last line in the file, or to
0373   the setting last saved.  You will only need to adjust it if there are footer
0374   lines in the file the importer should ignore.  Otherwise, you are likely to
0375   get a data error warning when the plugin attempts to parse incorrect
0376   data.  Again, if the <guilabel>End line</guilabel> selector does not respond,
0377   check the <guilabel>Start line</guilabel> setting.
0378 </para>
0379 </formalpara>
0381 <formalpara><title>Date format</title>
0382 <para>
0383   This needs to be set according to the order of year, month, and day in the
0384   dates in the file.  If the plugin finds data incompatible with this setting,
0385   it will complain when you try to import.  However, if the setting is wrong,
0386   but it produce invalid results not detected (such as data with no days higher
0387   than 12, so month and day could be switched) you will simply get incorrect data,
0388   because the plugin cannot know you made a mistake. In this case, the error will be
0389   obvious in the ledger after import.
0390 </para>
0391 </formalpara>
0393 <para>
0394   Once ready, the <guilabel>Next</guilabel> button will be enabled, and clicking
0395   it will advance the wizard.
0396 </para>
0397 </sect3>
0399 <sect3 id="details.impexp.csv.secsym">
0400 <title>CSV Import Wizard: Securities and Symbols</title>
0402 <para>
0403   For an Investment file, after the <guilabel>Lines</guilabel> page has been
0404   accepted, you need to assure that each security in the file is matched to the
0405   correct security in your &kmymoney; file, before import can proceed.  At this
0406   point, another window will open, showing the securities and symbols contained
0407   in the import file.  Note that unlike the data display in the main wizard
0408   windows, the changes you make on this page <emphasis>are</emphasis> imported.
0409 </para>
0411 <para>
0412   Completing this page is straightforward, if you consider these items:
0413   <itemizedlist>
0414     <listitem>
0415     <para>
0416       Each row represents one transaction, and so it may appear there are
0417       duplicate rows.  This is OK.
0418     </para>
0419     </listitem>
0421     <listitem>
0422     <para> 
0423       Each security name must match exactly the existing security as specified
0424       in &kmymoney;.  If it does not match, it will be created as a new
0425       security, which you probably do not want, unless it represents the
0426       purchase of a new security.
0427     </para>
0428     </listitem>
0430     <listitem>
0431     <para>
0432       A symbol must be shown for each security.
0433     </para>
0434     </listitem>
0436     <listitem>
0437     <para>
0438       The <emphasis>only</emphasis> information on this page should be the
0439       security symbol and name.  Any other information initially shown (such as
0440       date or activity type) is still in the actual import file, but should not
0441       be shown here.
0442     </para>
0443     </listitem>
0444   </itemizedlist>
0445 </para>
0447 <para>
0448   You can edit a symbol or security name by double clicking the cell.  For
0449   each security, if necessary, edit the name in one of its rows, If the correct
0450   security name appears in the imported file, double click on it to select it,
0451   then copy and paste/edit, taking care if you have used a variation or
0452   abbreviation within &kmymoney;.  If you edit a security name, that edit will
0453   be applied to all rows with the same symbol.
0454 </para>
0456 <para>
0457   Any line without a symbol will be treated as a brokerage-type checking
0458   item. If any transaction involves another account, &eg;, a checking or
0459   brokerage account for a received dividend or for making a payment, a message
0460   box will pop up for the account name to be entered for the transfer.  This
0461   will generally be the Brokerage account you chose or created when you created
0462   the Investment account.  Similarly enter the column number containing the
0463   payee, if requested. If a mistake is made when entering the account name, the
0464   import will go ahead, but &kmymoney; will not recognize it, and will flag
0465   those transactions as missing a category assignment.  If the required account
0466   name is rather long, just enter a few characters.  The import will proceed but
0467   the transactions will be flagged by &kmymoney; as missing a category
0468   assignment, and you will need to select the correct transfer account after the
0469   import. Click <guibutton>OK</guibutton> when done. The import process then gets
0470   handed over to &kmymoney;.
0471 </para>
0473 <para>
0474   If you have more that one transaction referring to the same security, you can
0475   edit all of them at once, using multi-select.  For instance, to add a symbol for
0476   several lines, press and hold the &Ctrl; key, and in the symbol column,
0477   select each transaction.  While still holding the &Ctrl; key,
0478   all those symbol cells should still be selected, so click on one and enter the
0479   symbol.  Click inside the window but outside that column, or hit
0480   &Enter; (not <guibutton>OK</guibutton>).  Now that those
0481   transactions all have the same symbol, double click one detail entry and edit
0482   the security name as you wish.  Click elsewhere on the window (or
0483   &Enter;) to accept the edit, which will then change all
0484   those entries.  The remaining entries will show the symbols picked up from the
0485   transactions in the import file.
0486 </para>
0488 <para>
0489   Now click <guibutton>OK</guibutton>, then <guibutton>Import</guibutton>.  In the
0490   <guilabel>Enter Account</guilabel> box, enter the name of a Brokerage/checking
0491   account for funds.  If you enter a valid name that account will be used.  If
0492   you can't be bothered entering a correct but long name, enter a few
0493   characters.  The import will accept that but the transactions in the ledger
0494   after import will need a proper account to be selected.  For the
0495   <guilabel>Brokerage</guilabel> box, enter the number of the column
0496   containing that detail. Now, on the <guilabel>Invalid transaction</guilabel>
0497   box you may get a few entries because the activity type does not match the
0498   qty/price/amount combination.  On each message, click <guilabel>Select
0499   Transaction Type</guilabel>, and a drop down will appear indicating valid
0500   activity types for that combination of values.
0501 </para>
0503 <para>
0504   Now the import has occurred and you're into &kmymoney; to select the investment
0505   account to use.  Then the checking account, if there were any brokerage type
0506   transactions.
0507 </para>
0508 </sect3>
0510 <sect3>
0511 <title>CSV Import Wizard: Finish</title>
0512 <para>
0513   On reaching the Final page, the plugin automatically validates the values.  If
0514   the numeric value column/s is/are highlighted in green, then the validation
0515   was successful and all that is necessary is to click <guibutton>Import
0516   CSV</guibutton> and control then passes to the main &kmymoney; program.
0517   However, if the start and/or end lines are incorrectly set, or if the wrong
0518   columns were selected, the highlighting will be in red, and an error message
0519   will appear indicating where the error lies.  The user will then need to click
0520   <guibutton>Back</guibutton> to get to the relevant page to correct the error.
0521 </para>
0523 <para>
0524   It might also be that if debit and credit columns are in use, one of those
0525   columns may legitimately contain no entries.  This would mean that that column
0526   has no decimal symbol present, and this would result in a warning.  If you see
0527   that this is the case, you may click either of the buttons to accept
0528   (<guibutton>Accept this</guibutton> or <guibutton>Accept all</guibutton>.)
0529 </para>
0531 <formalpara><title>Decimal Symbol</title>
0532 <para>
0533   Another possible problem might be that the selected decimal symbol is
0534   incorrect. Selecting the symbol to match the data should clear that error.
0535   Normally, you should not need to change this selection.  Note that the
0536   <guilabel>Decimal Symbol</guilabel> must be set to match your file, not your
0537   locale.  If your locale setting has a different value, conversion will be seen
0538   to take place.  The display of the file in the upper part of the window will
0539   show numeric fields highlighted in green if the current setting produces valid
0540   results, otherwise in red.  The highlighting also reflects the <guilabel>Start
0541   line</guilabel> and <guilabel>End line</guilabel> settings.  There could be
0542   warnings if any of the selected cells appear not to contain the selected
0543   symbol.
0544 </para>
0545 </formalpara>
0547 <formalpara><title>Thousands Symbol</title>
0548 <para>
0549   This does not need to be selected, as it is set automatically based on the
0550   <guilabel>Decimal Symbol</guilabel>. It is provided purely as a guide.  In
0551   addition, the selector will be inactive if none of the values to be imported
0552   is greater or equal to 1000.
0553 </para>
0554 </formalpara>
0556 <formalpara><title>Import CSV</title>
0557 <para>
0558   Clicking this button tells the plugin to actually import the data from the
0559   file, based on the choices you have made above.  &kmymoney; will prompt you
0560   for the correct account into which to import the data.
0561 </para>
0562 </formalpara>
0563 </sect3>
0565 <sect3>
0566 <title>Make QIF File</title>
0567 <para>
0568   This button gives you the ability, after the import has been completed, to
0569   save the data from the CSV file as a QIF file, should you require one for any
0570   reason. This was actually the original functionality that drove the creation
0571   of this plugin.  However, as &kmymoney; itself is now able to export a qif
0572   file, the capability is now probably of little use and is likely to be removed
0573   eventually.
0574 </para>
0575 </sect3>
0577 <sect3>
0578 <title>Finishing up</title>
0579 <para>
0580   For a <guilabel>Banking</guilabel> import, the plugin has finished, and
0581   &kmymoney; will prompt you, as stated above, for the correct account into
0582   which to import the data. For an <guilabel>Investment</guilabel> import,
0583   however, a little more may be required.  If, during import of a transaction,
0584   the plugin finds no valid transaction type, it will display the offending
0585   transaction, and the user may select a valid type to substitute, depending on
0586   the combination of quantity, price, and amount values.  For every transaction,
0587   the plugin will validate the column contents to ensure they match the action
0588   type.  For instance, if a quantity appears but no price or amount, it is
0589   assumed that the transaction can be only an Add or Remove Shares.  Or, if
0590   there is an amount but no quantity or price, then a Dividend is assumed, &etc;
0591 </para>
0593 <para>
0594   If you wish to save your settings, remember to click the
0595   <guibutton>Finish</guibutton> button, and the plugin will then close.
0596 </para>
0597 </sect3>
0599 <sect3>
0600 <title>Adding Investment Activity Types</title>
0601 <para>
0602   If you find that your investment statements keep including activity types that
0603   are not recognized, just add them to the section in the resource file.  (See
0604   <link linkend="details.impexp.csv.config">below</link> for more details on
0605   this file.) For instance, in the <literal>[InvestmentSettings]</literal> section
0606   of the file, the <literal>BuyParam</literal> field includes entries for
0607   <literal>Purchase</literal>, <literal>Buy</literal>, <literal>New Inv</literal>,
0608   and <literal>Switch In</literal>. If you find a different one, add it to the
0609   correct list and restart the plugin. You may notice that there are similarities
0610   in the entries in different fields, and you may find that the wrong activity type
0611   is being selected. The plugin checks these lists in the following order:
0612   <literal>Shrsin</literal>, <literal>DivX</literal>, <literal>Reinvdiv</literal>,
0613   <literal>Brokerage</literal>, <literal>Buy</literal>, <literal>Sell</literal>, and
0614   <literal>Remove</literal>. Re-ordering the lists to suit this does not work as
0615   might be expected, since the entries in the resource file get sorted into
0616   alphabetical order. If the offending parameter is one you don't need, just delete
0617   it from the file. If that is not possible, you may need to edit your file before input.
0618 </para>
0619 </sect3>
0621 <sect3 id="details.impexp.csv.config">
0622 <title>Configuration of CSV importer plugin</title>
0624 <para>
0625  A well-known drawback of QIF format is that it is a fairly loose format.
0626  With CSV files, there is this same problem, only more so, in that there  is
0627  no agreed standard at all.  With investment files, in particular, there is
0628  much more scope for variation in specifying the different types of activities
0629  represented in the data.  The plugin handles this by listing these activity
0630  types in a resource file, called <filename>csvimporterrc</filename>. The location
0631  of this file depends on your distribution. On a &Linux; system, this will be in
0632  <filename class="directory">$KDEHOME/share/config</filename> where
0633  <envar>$KDEHOME</envar> is usually <quote>.config</quote> within your home folder.
0634  If you are migrating from a version of &kmymoney; prior to 5.0 or later, the old
0635  location of <envar>$KDEHOME</envar> was <filename class="directory">.kde4</filename>.
0636  Using this resource file allows the user to add an activity type that the developer
0637  had not encountered. If the file does not exist when the importer first runs, the
0638  plugin will create a default version, containing a few of the more obvious
0639  descriptions.
0640 </para>
0642 <para>
0643  A number of sample CSV files are provided (in the <filename class="directory">
0644  kmymoney/contrib/csvimporter/</filename> folder in the source tree) in the hope
0645  that they may help.  For example, in the investment sample, an activity type is
0646  "<literal>ReInvestorContract Buy : ReInvested Units</literal>". In the validation
0647  process, the first successful match is on the <literal>ReInv</literal> in
0648  <literal>ReInvestorContract Buy</literal>, so the transaction therefore gets
0649  classed as <literal>Reinvdiv</literal>, even though <literal>Buy</literal> also is
0650  mentioned. Another example which has been observed is an activity type of
0651  <literal>Reinvest</literal> even though the transaction included neither price nor
0652  amount, but only a quantity, so that needed to be treated as <literal>Add
0653  Shares</literal>, or <literal>Shrsin</literal>.
0654 </para>
0656 <para>
0657  When this plugin was created, only a few investment formats had been seen as
0658  examples, and it may well be that you will encounter one which cannot be
0659  handled correctly.  If you find such a file, please send a suitable example
0660  (edited to remove or replace personal information) to the &kmymoney; user list
0661  &userlist; or developer list &devlist;, the developer will do his best to
0662  modify the plugin to handle it.
0663 </para>
0664 </sect3>
0665 </sect2>
0666 </sect1>