Ace Jones

acejones@users.sourceforge.net

2009-06-14 1.0 Investments are instruments for investing money that are traded on a market. Stocks, bonds, and mutual funds are the most common investments; so they are 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. Each investment has a Base Currency. This is the currency in which it is traded. 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 (New York Stock Exchange) would be in US dollars, and one on an Australian market would be in Australian dollars. Investment Accounts hold a collection of investments. An Investment account contains transactions, such as buys and sells, of those investments. 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. An investment account often 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. The first step on the path to working with investments is to create an account to hold your investments. Choose Account 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 have just created from the Select Account dropdown box. 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. 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. The first thing you'll be asked to enter is the type of investment, whether it's a stock, bond, etc. Next, the investment details page is presented. The following information is entered on this page: Trading Symbol. The ticker symbol used to identify the investment on whatever market it trades. &kappname; requires a trading symbol for all investments; however some investments do not have symbols. In this case, you will need to make up a symbol for it. Full name. The friendly, readable name of the investment you're creating, e.g., Advanced Micro Devices, Inc. This name is also referred to as the security. Fraction. The degree of precision to which your holdings are measured. For example, in the US most mutual funds measure holdings to three decimal places, so you would enter 1000 in this field. Stocks are often measured to only whole units, so you could enter 1 for a stock like this. Trading market. Where the stock trades. This is an optional field which is provided for your convenience. This information is not used anywhere else in &kappname;. Identification. An optional field to enter additional identification information you might like to keep track of. Again, this information is not used anywhere else. Trading currency. The underlying currency in which this investment trades on its market. Price entry. Choose whether the price will be entered as an individual price, or as the total for all shares. 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. Finally, you're presented with the Online Update screen. This is where you tell &kappname; how you would like to update the prices of your investment. The following items are set here: Use Finance::Quote. This is an option for GnuCash users who are used to this style of quotes. Most users can leave this unchecked. Online Source. The online source you'd like to use for this particular investment. The most common choice is Yahoo. Try that first, and if the investment cannot be found using this source, then experiment with the others. Factor. A multiplier that should be applied to quotes retrieved for this investment. This is most commonly needed for UK stocks where the price quoted is in pence (1/100), and the stock is denominated in pounds. In this case, enter 0,01 for the Factor. The Investment view window lists your current holdings in this account, along with their symbol, value, and price. Right-click the mouse on any of the investments to bring up the Investment Options context menu, where you have the option to add, edit, or delete individual investments from this account. Also, you can update the price of your investments here either manually or via their online source. In addition, it is possible to close an empty account, or to reopen a closed account. Investment Transaction Form Investment Transaction Form Investment transactions are entered and edited in the ledger view, as with other kinds of accounts. However, the fields are different, and vary depending on the investment transaction type or activity. Investment transactions have some additional elements: Activity Security Account Shares, Price, & Total Amount Fees Interest category 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 disbursement 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. Split Shares. Used when the stock is split. Enter the ratio of the split in the Split Ratio field. For example, in a 3:2 split, enter 1.5 Each investment transaction must be associated with an individual security, which is here just another name for an investment. Choose the investment name when adding or editing a transaction. The symbol will be displayed when viewing it. For any transactions which generate or require money, you must enter the account where the money is transferred to/from. If your investment account has an associated brokerage account, it's usually best to transfer the funds there. This applies to funds for purchase or sale of the investment, as well as for fees paid or interest or dividends earned. For buy, sell, and cash dividend transactions, the number of shares, the price per share, 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 the total amount and the number of shares, because these are the known facts of the transaction. The price per share can be calculated from these. With many investment transactions you can include the fees (or commission) you paid the broker. If you enter a category for the fee, then a field will be shown to the right where you can enter the amount of the fee. If you need to enter more than one fee for the transaction, you can use the Split Transactions feature. In this case, when you complete entering all the splits, the total amount of the fees will be shown to the right. This is how you enter an interest or dividend payment from an invenstment. As with fees, if you enter a category, then a field will be shown to the right where you can enter the amount. You can also use the split transaction feature, if required. &kappname; supports multiple currencies and investments, and you may want to combine the two. However, 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 investment, 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 as EUR 2,254.54, assuming an exchange rate is 11.0000 SEK / EUR. There are two ways of updating the prices for your investments. You can either enter the new price manually or have &kappname; fetch it from the web. You can enter prices for your investments using the same Price Editor as used for currencies. &kappname; has the ability to download the latest prices for your investments and currencies via the web. At your request, &kappname; will fetch a page from the web that contains the latest price for each item. By default, prices are fetched from http://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. To find the trading symbol for a security supported by Yahoo, use the Symbol Lookup feature at http://finance.yahoo.com. 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 Investment .... In the Investment Detail Wizard, click Next twice, for the Online Update section. In the Online source dropdown box, select the online source. Versions of &kappname; starting with 0.9 contain support for the Finance::Quote package for obtaining online quotes. This is intended primarily as a convenience for those users converting from the GnuCash finance package, which uses it as its native method. If you do select this option, you should see a different list of sources, those supported by Finance::Quote. If the list is empty, it suggests that the package is not properly installed. See their web site at http://finance-quote.sourceforge.net for more information. Some online sources do not report the price in a base quantity (e.g., EUR) but in a fraction (e.g., Cent). Using this information as price will produce wrong values for your investments. If this is the case for your online source, you can use the Factor field to enter an adjusting factor. For the above mentioned example the factor would be 0.01. The Factor field is only available if a Quote Source has been selected. Typically, you will update the prices for all your investments and currencies at once. Choose the ToolsUpdate 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 Adding or editing 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 SettingsConfigure &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 currency. 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 contains custom quote logic, taking the symbol as a single parameter. 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 extract those items from the page. Please review the documentation for the QRegExp class at http://qt.nokia.com/doc/3.3/qregexp.html#1 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. Certain common features that are normally found with investments are not yet implemented in &kappname;. These include: Derivatives (options, futures, etc), capital gains, and tax reporting for investments.