&Ace.Jones; &Ace.Jones.mail;
2011-07-3
4.6

# Importeren en exporteren

&Tony.Bloomfield; &Tony.Bloomfield.mail;

## GnuCash-importeerprogramma

### GnuCash-bestanden

Het importeerprogramma van &kappname; voor GnuCash behandelt het direct lezen van standaard (&XML;) bestanden zoals geproduceerd door de versies 1.8 en 2.0 van GnuCash. De volgenden worden niet ondersteund:

- importeren van gegevens uit een database (Postgres)

- importeren van 'multi-book'-bestanden

- importeren naar een bestaand bestand van &kappname;

- importeren van specifieke functies voor kleine bedrijven (personeel, rekeningen, etc.)

- exporteren naar bestanden van GnuCash.

Het importeren zal waarschijnlijk alleen juist werken als het een geldig bestand krijgt aangeboden. Het is aanbevolen om de functie GnuCash Alles controleren & repareren (in het menu Acties) uit te voeren alvorens importeren te proberen.

Bestanden kunnen geopend worden door de bestandsnaam op de opdrachtregel te specificeren (`kmymoney <pad naar bestand>`) of met de menu-items van &kappname; &Ctrl;O Bestand Openen of Bestand Importeren .

De overeenkomst tussen de twee producten betekent dat veel dagelijkse gegevens op een rechtstreekse manier geïmporteerd kunnen worden. Er zijn echter enige gebieden waar zich verschillen voordoen en verschillende mogelijkheden geboden worden om hiermee om te gaan. De volgende secties zullen enkele van deze verschillen beschrijven; ze begrijpen zou moeten leiden tot beter importeren.

### Overeenkomsten, verschillen en terminologie

#### Gebruik in midden en klein bedrijf

Het moet opgemerkt worden dat &kappname; een persoonlijke financiële beheerder is, end op zich niet direct elke van de zakelijke functies van GnuCash ondersteunt, zoals belastingtabellen, salarissen en opzoekwerk. Elke crediteuren of debiteurenrekening die wordt gevonden in een bestand zal respectievelijk geïmporteerd worden als schulden- of bezittengenrekening.

#### Rekeningen

##### Typen rekeningen

For both products, the highest level of structure in the file is the account. &kappname; supports 5 main types of account: Asset, Liability, Income, Expense and Equity, each of which may have various subtypes, &eg;, Checking, Credit Card, &etc; &kappname; includes a 'standard' account for each of these five types, and all other accounts are held subordinate to one of these. &kappname; enforces more consistency (or less flexibility, depending on your point of view) between account types than does GnuCash, and the importer will correct any inconsistencies it detects. This may result in a slightly different account structure, though this can, within reason, be amended after the import is complete.

##### Categorieën

&kappname; uses the term Category to denote an account of an Income or Expense type. Unlike GnuCash, these are not considered as 'ledger' accounts, and entry of transactions folder into categories is not supported; allocations are made during transaction entry into other account types.

##### Structuur en plaatshouders

GnuCash supports the use of Placeholder accounts. In effect, these are just read-only accounts into which no transactions can be entered, but which function in an analogous fashion to folders in a folder structure, as a holder for other accounts. Though &kappname; does not support this feature as such, it does provide a parent/child account relationship, so the importer simulates placeholders by creating empty accounts.

##### Rekeningtype overeenkomst

GnuCash-type | &kappname;-type
--- | ---
BANK | Controleren
CONTROLEREN... | Controleren
SPAARREKENING | Spaarrekening
BEZIT | Bezit
KAS | Kas
VALUTA | Kas
MONEYMRKT | MoneyMarket
AANDEEL | Aandeel
MUTUAL | Aandeel
AANDEEL | Aandeel
VERPLICHTINGEN | Verplichtingen
KREDIET | Creditcard
INKOMEN | Inkomsten
UITGAVEN | Uitgaven
DEBITEUREN | Bezit
CREDITEUREN | Verplichtingen

#### Transacties en splitsingen

##### Gebalanceerde transacties

Zoals met GnuCash worden gegevens ingevoerd in de vorm van transacties, elk in het algemeen bestaande uit 2 of meer gesplitste items. In feite zullen geldige GnuCash transacties altijd minstens 2 gesplitste bevatten en in overeenstemming zijn met de boekhoudstandaard van GnuCash, dubbele items, deze moeten in cijfermatige balans zijn (dwz. ze moeten samen nul zijn). &kappname; moedigt deze standaard aan, maar forceert deze niet, maar elke geïmporteerde transactie die niet gebalanceerd is zal de weergave van de boekhouding gemarkeerd worden als een probleem.

##### Begunstigden

&kappname; geeft er de voorkeur aan dat alle transacties een begunstigde hebben (een algemene term die zowel betalers als betaalden omvat) en anders dan GnuCash, wordt een lijst van deze begunstigden bijgehouden. Namen van begunstigden worden gegenereerd door het importeerprogramma uit het veld Beschrijving van de GnuCash transaction.

##### Overboekingen

&kappname; uses the term Transfer to describe a transaction which does not involve a Category, but only transfers money between Asset and/or Liability accounts.

##### Transactie controle

&kappname; provides an account reconciliation function similar to that of GnuCash, and the corresponding transaction status will be imported.

#### Commodities

GnuCash uses the term Commodity to cover both currencies and non-currency assets. These are treated separately in &kappname;.

##### Valuta's

&kappname; has built-in support for all foreign currency types. &kappname; also requires that the user specify a base currency, this being the default currency for new accounts. The importer will attempt to determine the most likely base currency, though this choice may be rejected in favor of an alternative.

(NOTE: &kappname; does not currently support accounts denominated in 'defunct' currencies (except those replaced by the Euro). At present, it will be necessary to remove any such accounts from your GnuCash file before importing. We hope to improve on this situation in a future release.)

##### Securities and Investments

Non-currency assets (normally stocks and bonds) are called Securities by &kappname;, and represent the main difference between the two products, in that &kappname; requires any account denominated in a security to be subordinate to an Investment Account. This is described in more detail in the chapter on Investments. 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:

- Create a separate Investment account for each security, with the same name as the security

- Create a single Investment account which will act as 'parent' for all security accounts

- Create several Investment accounts, and assign securities to them as directed by the user.

It depends entirely on user requirements which of these options is relevant in each situation, and in some cases, manual restructuring of accounts after importation may be necessary.

##### Prices and currency rates

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.

##### Online koersen

For obtaining online price and currency rate quotations, GnuCash uses a package called Finance::Quote. Recent versions of &kappname; contain support for this package for obtaining stock quotes, and this will be used by default when importing data. You may however select to convert to the native method used by &kappname; which is covered in more detail in online quotes.

If you choose to do so, the following dialog will allow selection of a 'native' &kappname; price source, or a user-defined source, for each account for which online quotes are required. However, the stock (ticker) symbol will be imported unchanged. Since this symbol will almost certainly be different in the two packages, it will need to be manually edited after completion of the import process. Future currency rate updates will not use Finance::Quote, and will always use the native retrieval method.

#### Periodieke Transacties

&kappname; does not retain the separation made in GnuCash between template transactions and their frequency of occurrence. Transaction data will be duplicated if the same template is used in different schedules, but this is not likely to be of great significance.

##### Schedule types

&kappname; classifies all schedules as one of three types, Bills, Deposits, or Transfers. Since GnuCash does not make such a distinction, the importer attempts to determine the classification from the accounts and direction of money movements. It may be that in some cases incorrect assumptions are made, and these will need manual correction.

##### Suspect Schedules

Some features of GnuCash scheduled transactions are not available in &kappname;, so the importer tries in each case to reach a reasonable compromise in converting the data. These transactions will be flagged as suspect, and the user will be given the option of editing them directly during the import process. Examples of situations which may cause this are:

- some frequency intervals supported in GnuCash are not currently available in &kappname;

- &kappname; does not support the use of formulae and variables in amount fields

- complex cases which have not yet been identified for import.

Despite best efforts, it is possible that, due to the many options involved, a scheduled transaction may cause a fatal error within &kappname;. If this sort of problem seems to be occurring, the importer offers the option to drop all suspect schedules.

#### Rapporten

&kappname; provides a comprehensive selection of configurable reports, described in more detail in Reports. These will not necessarily, however, match precisely those reports available in GnuCash.

### Selecting Importer Options

#### Investerings handeling

See "Securities and Investments" above.

#### Online koersen

Turn this off if you wish to use the native method for future online price quotes.

See "Online Quotes" above.

#### Periodieke Transacties

See "Scheduled Transactions" above.

#### Decoding Options

If your native language is written in letters or symbols which are different from those used in the 'Latin' languages (i.e., generally Western European), these are represented in a special fashion ('encoded') in your GnuCash file. If these letters are not displayed correctly on your screen, then they must be decoded. Currently, it is often not possible to detect accurately which form of decoding must be used, so you may need to set this option and select an entry from the list. In general, the first item in the list will be that which is considered appropriate for your locale (i.e., the country and language which was selected as native when your operating system was installed), so this should be tried first. Since the import process does not overwrite your GnuCash file, you are free to experiment with any of these selections.

#### Optie voor transactienotitie

Under some usage conditions, non-split GnuCash transactions may contain residual, often incorrect, memo data which is not normally visible to the user. When imported into &kappname; however, due to display differences, this data can become visible. Often, these transactions will have a Notes field describing the real purpose of the transaction. If this option is selected, these notes, if present, will be used to override the extraneous memo data.

#### Debug Opties

These need only be used in the event of import problems. If you have such problems, you should also report them to the &kappname; developer list &devlist;. Note that the traces produced by these options may contain data of a confidential nature, and the Anonymize option should be used if they are to be made publicly available.

### Import Report

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:

- Record counts

- Inconsistencies in account types and actions taken

- Details of suspect schedules

&Thomas.Baumgart; &Thomas.Baumgart.mail;

## QIF Importer

### QIF format considered harmful

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:

- Lack of standardized format: Different versions of the same program will impart different meanings to the same element.

- Lack of transaction identifier: Because there is no ID number associated with each transaction, matching duplicate transactions is haphazard at best.

- Lack of expressiveness: The grammar is really simple, and cannot portray the depth of financial information found in today's financial environment.

This is generally why Intuit stopped supporting QIF input at all with Quicken 2005. If you have the option of getting data some other way, like OFX, always choose that option.

### How to import a QIF file

To import a QIF file, first ensure you have a valid &kappname; file open. Then select Import QIF... from the File menu.

The resulting dialog prompts for the QIF filename allowing you to locate the file by clicking on the Browse button.

Also, &kappname; differentiates between the import of a bank statement file and historic data exported from another application. The default is to import a bank statement file. In case you are importing data from your previous personal finance manager application select the appropriate option.

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 next section for more details on that subject.

Click on Import to import the QIF file.

&kappname; will start scanning the file to determine the formats used to represent dates and numbers. In case it cannot determine a date format unambiguously, &kappname; will ask the user to select one from the list of possible date formats.

Next, &kappname; imports the data and creates all necessary objects, such as payee information, accounts and category records, and stock price information. Wherever possible, existing transactions will be matched against the imported information. A progress bar is shown and updated during the import process.

In case &kappname; could not detect the name of the account to be imported, the user will be asked to select the account into which the data should be imported. If the account does not already exist in your file, a new account can be created by clicking on Create.

At the end of the import, &kappname; shows a statement import statistics window.

Statement statistics Statement statistics

After importing, all of the imported transactions will be shown with a yellow background in the ledger view. In case &kappname; was able to match an imported transaction with an already existing transaction, the background is shown in light green.

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.

The colors used to mark imported and matched transactions are customizable and may be different in your environment.

### Setting up a QIF profile

Because there is no universally standard format for a QIF file, different vendors have taken liberties with the format, and introduced their own nuances. The QIF Profile allows &kappname; to know about the peculiarities of your file. To edit an existing QIF Profile, or to create a new one, press the New button on the QIF Import dialog, near the profile selector.

QIF profiel editor

Previous versions of &kappname; used to have a tab for date and amount specifications. &kappname; now determines those settings by scanning the file. If it cannot figure out all settings, it will interrogate the user during import.

### Transactie vergelijking

As noted previously, one of the major drawbacks of the QIF format is the lack of a unique identifier for each transaction. Thus, if you import a QIF file and some of the transactions are already in your ledger, you may get duplicates. &kappname; attempts to get around this by looking for transactions that look similar to those you already have. If it finds something that looks like the same transaction, it will match the apparent duplicate.

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.

### Writing an import filter

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, &kappname; includes a CSV Importer Plugin, but you can still import other types of files into &kappname; using a QIF Import Filter. A filter is a custom program you write which takes your special file as input, and produces a QIF file as output. This can be a shell script, a perl script, a compiled program written in C/C++, or anything else you can dream of, as long as the system can run it.

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.

A common problem is to convert a list of comma-separated-values into a QIF file. This is a textbook case for the awk tool. Create a script called csv2qif.awk, with the following two lines as contents:

    BEGIN { FS=","; print "!Type:Bank" }

            { print "D"$1; print "T"$2; print "N"$3; print "P"$4; print "M"$5; print "^" }

Then, change the QIF keys (D,T,N,P,M) to match the order of your csv data. Set the input filter to `awk -f csv2qif.awk`.

Another problem sometimes arises in the encoding of QIF files. &kappname; expects files to be UTF8 encoded. If your file is encoded in something else, it can be useful to convert it to UTF8. For example to convert it from iso-8859-1, you would set the input filter to `recode iso-8859-1..utf-8`.

### Special &kappname; QIF extensions

As already mentioned, one of the major drawbacks of the QIF format is the lack of a unique identifier for each transaction. If you are writing your own QIF file creator (or filter, as described above), you can overcome this problem. &kappname; supports the '#' field. The importer will interpret this as a unique transaction ID, and disregard the record if the transaction is already in the system.

## QIF Exporter

To export one of your accounts to a QIF file, choose the Export QIF from the File menu. You will be prompted for which single account to export, what file to export it to, and what QIF Profile to use.

At the moment, QIF Exporter does not handle export of investments.

QIF Export

&Ace.Jones; &Ace.Jones.mail;
&Thomas.Baumgart; &Thomas.Baumgart.mail;

## OFX Importer Plugin

### De plug-in ophalen

&kappname; will import OFX files painlessly. However, this functionality is not built into the core program. You must obtain and install the OFX Importer Plugin. Once that is installed, the command to import OFX files will automatically show up under the File Import menu.

Note that many prepackaged versions of &kappname; were built with the OFX importer already included or available as a separate package. If the OFX importer does not seem to be installed in your version, the first place to check is in the same place you got your base &kappname; package.

If you have installed from RPM, the OFX Importer Plugin is contained within the kmymoney-ofx RPM. It should be available from whatever source you got the base &kappname; RPM. If you have built from sources, all you need to do is have preferably the libOFX 0.9 development headers and libraries installed on your system. The &kappname; build process will detect these and compile the plugin. At the time of release of &kappname; 4.6, the latest libofx version was 0.9.4, which is also the minimum required version.

Should you run into trouble trying to compile &kappname;, and you are certain you have the correct version of libOFX installed, please contact the developers list &devlist; for assistance. Include a copy of your config.log file, compressed first via gzip.

### What is OFX

OFX stands for Open Financial Exchange. According to the OFX web site Open Financial Exchange (OFX) is a unified specification for the electronic exchange of financial data between financial institutions, businesses and consumers via the Internet. OFX is not a financial institution. The specification defines formats for transfer of financial data both by file and by direct interchange.

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 OFX or QFX (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.

Another site with good information is OFX Home. They maintain a directory of financial institutions that support OFX. This can be useful if you have problems setting up OFX direct connect. They also have a forum for discussions about OFX issues.

### Importing an OFX file

The most basic way to import an OFX file is to choose the importer from the menu bar. From the File menu, choose Import, and then OFX.... If OFX does not show up under Import, you do not have the OFX Importer Plugin installed correctly. Please see the previous section.

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.

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.

Please note that this section describes the native OFX importer. OFX files may also be imported using the AqBanking Importer Plugin if you have installed that. Note that the two importers do behave slightly differently, and they are written and supported by two different developers.

### Importing Investments

Please note that if you are importing a file with investment transactions, those investments must first exist in your &kappname; file. The trading symbol is used to match, so please ensure that the symbol in &kappname; is exactly the same as the one in the file you're importing.

### Web Connect

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 &kappname;. It will then import the downloaded OFX file into the &kappname; file you most recently had open. You can also change the file associations of your desktop environment, and have &kappname; open the OFX file automatically for you.

If you need to import the OFX file into some other &kappname; file, load up that file in &kappname; first, and then visit your bank's web site.

### Direct Connect

OFX Direct Connect is now supported in &kappname;. This gives you the ability to contact your bank directly to obtain statements. In the future, there will be more help written, and this will be moved to its own section.

To enable this feature, you must compile &kappname; with the --enable-ofxbanking switch (now the default).

Please be warned: Many banks require a separate signup, will give you a separate password or PIN, and may even charge you a separate fee for this service. No bank directly supports &kappname;. You will have to tell them you want to bank directly from MS Money or Quicken.

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 Map to online account.... In case more than one online banking plugin is installed on your system you will be asked which one to use. For the internal OFX method select KMyMoney OFX. A list of banks will be downloaded from the Internet and a wizard will guide you through choosing a bank, entering your username and password, and selecting an account. Should you find that your bank is not listed, then it may still be possible to use the manual option. Your bank may be able to provide the required parameters, or you may have to do some research to find them.

Setting up OFX Direct Connect can sometimes be a challenge, especially as the implementation 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 &kappname; 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 &kappname; developer list &devlist;.

Once you have an account set up with online banking, go to the ledger for that account. Then from the Account menu, choose Update account.... This will connect to your bank, and download a statement for the last 60 days.

In version of &kappname; prior to 4.6, the payee name was always taken from the PAYEEID field. As of version 4.6, the payee name can be based on either the PAYEEID, NAME, or MEMO field in the OFX transaction. You can configure this feature and some other OFX direct connect settings by selecting the appropriate tab in the Edit account dialog.

### Exporting an OFX file

It is not possible to export your data as an OFX file currently. If you are interested to contribute in this area, please contact the libofx development team for details.

&details-impexp-csv;

## Writing Importer Plugins

&kappname; contains explicit support for importer plugins. If you have a custom format, and you would like to write an importer plugin, we would value your contribution. To do so, you'll need to compile the program from source. Then use the OFX Importer Plugin as an example.