Ace
Jones

    acejones@users.sourceforge.net

2005-07-20
0.8

# Investments

## Investments in &kappname;

### Investments

Investments are instruments for investing money that are traded on a market. Stocks, bonds, and mutual funds are the most common investments, so they're the ones supported most directly. Futures, commodities, options and more complex derivatives are also sometimes used, but &kappname; has no special functionality for them. As long as they behave like a stock or a bond, they can be tracked easily.

### Base Currency

Each investment has a Base Currency. This is the currency it's traded in. When a price quote is entered for an investment, the currency of the value given is always its base currency. A stock on the NYSE would be in US dollars, and one on the Australian markets would be in Australian dollars.

### Investment Accounts

Investment Accounts hold a collection of investments. Transactions, such as buys and sells, of those investments are contained in an Investment Account. All transactions in an Investment account must relate to a specific investment. There is no separate "cash balance" in an investment account. For that, you need a Brokerage Account.

### Brokerage Accounts

Often an investment account has an associated Brokerage Account. This is also sometimes referred to as a "Cash Account". Investment accounts cannot contain cash transactions, like a transfer from your bank. When a stock is sold, the proceeds are typically placed in the Brokerage Account.

When you create an Investment Account, you have the option of creating an associated Brokerage Account with it.

## Creating an Investment Account

The first step on the path to working with investments is to create an account to hold your investments. Choose Account Add new account... to begin the process of adding a new account. Create an account as usual, making sure to choose "Investment" as the type of account.

To work with the new investment account, navigate to the Investments view, and choose the account you just created from the Select Account drop-down box.

## Adding Investments to Your Account

To add individual Investments to your Investment Account, navigate to the Investments view, and choose the account where the investment is held from the Select Account drop-down box. Ensure you are looking at the Investment Summary tab.

Right-click the mouse in the empty space in the view. This brings up the Investment Options context menu. Choose New... from this menu. This launches the New Investment Wizard which you use to create your new Investment.

If you are using Online Quotes, ensure that the symbol exactly matches the symbol used by your quote source. Yahoo covers most of the world's markets, and requires a suffix on the end of symbols outside the US. For example, Rubicon Limited on the New Zealand market should be entered as "RBC.NZ".

## Investment Summary Information

The Investment Summary tab lists your current holdings in this account, along with their price and value.

It's also the place to add, edit or delete indivdual investments from this account. Likewise, you can update the price of your investments here either manually or via their online source. To perform any of these, right-click the mouse on any of the investments to bring up the Investment Options context menu.

## Investment Transactions

Investment Transaction Form Investment Transaction Form

The investment ledger is almost the same as the ledger for other kinds of accounts. Investment transactions have some additional elements:

1. Activity

2. Symbol Name

3. Shares & Price

4. Fees

5. Account

### Activity

The Activity for an investment transaction describes what action is happening to the stock. The following activities are supported:

- Buy/Sell. Use to record purchases or sales of individual investments. This action requires an account to transfer the funds from/to.

- Dividend/Yield. Also known as a "Cash Dividend", this action is used for when you receive an interest or dividend disbersement from your investment. This action requires an account to transfer the funds from/to.

- Reinvest Dividend. This is a dividend where the proceeds are re-invested back into the investment.

- Add/Remove Shares. A simple increase or decrease in your balance. This should be used very rarely, because it's uncommon for shares to just show up in your account (or disappear) unless it's a purchase or a sale.

### Symbol Name

Each investment transaction must be associated with an indvidual investment. Choose the investment name when adding or editing a transaction. The symbol will be displayed when viewing it.

### Shares, Price & Total Amount

For buy, sell, and cash dividend transactions, the number of shares, the price, and the total amount of the transaction must be established. You can enter any two of these, and &kappname; will calculate the third. It's usually best to enter just just the total amount and the shares, because these are the known facts of the transaction. The price can be calculated from these.

### Fees

With many investment transactions you can include the fees (or commission) you paid the broker. There is a space for the amount of the fee and the category to which you wish to assign it.

### Account

For any transactions which generate or require money, you must enter the account where the money is transferred from/to. If your investment account has an associated brokerage account, it's usually best to transfer the funds there.

## Working With Foreign Investments

Now that &kappname; supports multiple currencies and investments, you'd probably like to combine the two. Doing so requires extra care. As noted above, when you added an investment, you had to specify its trading currency. This might not be the same as your base currency, and it also might not be the same as the account in which you hold the stock or the account where you transfer your funds to/from for buys/sells.

Consider a hypothetical case. Your base currency is USD. You have an investment account in EUR, and a brokerage account also in EUR. In that account, you hold shares of TietoEnator, which is traded in SEK.

When you enter a buy transaction on this investement, use SEK as the currency. So if you buy 100 shares at a price of SEK 248.00, for a total of SEK 24,800.00, enter these values in the transaction.

Currency Warning Currency Warning

When you choose the brokerage account to fund the transfer, you'll be warned that it's in a different currency.

Exchange Rate Editor Exchange Rate Editor

When you finish the transaction, you will be prompted for a price update to the investment account's currency, in this case, SEK -> EUR. Review the documentation on Entering Prices Manually for more information on the price dialog.

If you then switch over to the brokerage account, you will see the transaction in EUR, or 2,430.48 in this case.

## Updating Prices

You can enter prices for your investments using the same Price Editor as used for currencies. Or you can fetch them electronically, using Online Price Quotes.

## Online Price Quotes

### How Online Quotes Work

KMyMoney has the ability to download the latest prices for your investments and currencies via the web. At your request, it will fetch a page from the web that contains the latest price for each item. By default, prices are fetched from finance.yahoo.com, and are subject to the terms and conditions of that site.

The online quote lookup uses the investment's trading symbol to find the price. Therefore, it's important to set the symbol correctly. Yahoo supports stocks from most major world markets, so it's usually just a matter of finding the correct symbol. For example, TietoEnator trades on the Stockholm Stock Exchange market, and its Yahoo symbol is TIEN.ST.

### Assigning a Quote Source

In order to get online price quotes, you first have to enable it for each investment or currency you want updated by setting a "Online Quote Source". This is the name of the service from which the quote should be fetched. KMyMoney ships with several sources to choose from. Yahoo is the recommended default source, and should work for most investments and all currencies.

To assign a quote source to an investment, navigate to the investment summary view for the account in which the security is held. Edit the security by right-clicking it and selecting Edit. Choose the Quote Source tab. Pick the appropriate source from the drop-down menu.

### Fetching Quotes

Typically, you will update the prices for all your investments and currencies at once. Choose the Tools Update Stock and Currency Prices... menu option to bring up the online price quotes dialog. Press Update All to fetch quotes for all investments and currencies in your &kappname; file.

Update Stock and Currency Prices Online Stock and Currency Price Update

### Editing or Adding Quote Sources

Editing or adding quote sources is not recommended for anyone but the most technical user. You should feel comfortable reading HTML, and writing complex regular expressions. If this doesn't sound like you, we recommend writing to the developer's list if none of the quote sources work for you. Ideally, please point us to a web page where these quotes can be obtained.

If you do feel up to the challenge, here's how it works. The quote sources are contained in the settings dialog. Choose Tools Configure &kappname;. From there, choose the Online Quotes section. You can choose an existing source to edit, or create a new one. When you are done with your changes, be sure to press the Update button before exiting the dialog. Your changes are not saved by default.

The first thing to worry about in an online quote source is the URL. This is the page that is fetched from the web. You will see a %1 in all sources, and a %2 in currency sources. For investments, %1 is replaced by the trading symbol. For currencies, %1 is replaced by the From currency, and %2 is replaced by the To. This URL is then fetched, all HTML tags are removed, and that stripped file is then sent to the page parser.

Note that the URL can also be a file: URL, which the quote fetcher takes to mean an executable script. It will pass any command-line arguments to it that you have specified, and feed the stdout to the page parser. For example, you might have a script called getquote.sh that contained custom quote logic, taking the symbol as a single paramenter. Your URL would be "file:/path/to/getquote.sh %1".

The page parser looks for a symbol, a date, and a price. Regular expressions tell it how to rip those items out of the page. Please review the documentation for the QRegExp class at doc.trolltech.com for the exact makeup of the regular expressions. There should be exactly one capture expression, surrounded by parentheses, in each regexp. The date format further tells the date parser the order of year, month, and day. This date format should always be in the form "%x %x %x". where x is y, m, or d. The date parser is very smart. "%m %d %y" will parse "December 31st, 2005" as easily as "12/31/05". Two digit years are interpreted as being in the range of 1950-2049.

## Unimplemented Features

Certain common features that are normally found with investments are not yet implemented in &kappname;. These include: Stock splits, derivatives (options, futures, etc), capital gains and tax reporting for investments.