<chapter id="details.investments">
<chapterinfo>
<authorgroup>
<author>
<firstname>Ace</firstname>
<surname>Jones</surname>
<affiliation><address><email>acejones@users.sourceforge.net</email></address></affiliation>
</author>
</authorgroup>
<date>2005-07-20</date>
<releaseinfo>0.8</releaseinfo>
</chapterinfo>

<title>Investments</title>

<sect1 id="details.investments.overview">

            <title>Investments in &kappname;</title>

<sect2><title>Investments</title>
<para>
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.
</para>
</sect2>

<sect2><title>Base Currency</title>
<para>
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.
</para>
</sect2>

<sect2><title>Investment Accounts</title>
<para>
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 &quot;cash balance&quot; in an investment account.
For that, you need a Brokerage Account.
</para>
</sect2>

<sect2><title>Brokerage Accounts</title>
<para>
Often an investment account has an associated Brokerage Account.
This is also sometimes referred to as a &quot;Cash Account&quot;.
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.
</para>

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

</sect2>

</sect1>

<sect1 id="details.investments.investment">

            <title>Creating an Investment Account</title>

<para>
  The first step on the path to working with investments is to create an account to hold your investments.
  Choose   
<menuchoice>
<guimenu>Account</guimenu>
<guimenuitem>Add new account...</guimenuitem>
</menuchoice>
 to begin the process of adding a new account.  Create an account as usual, making sure to choose &quot;Investment&quot; as the type of account.
</para>
<para>
  To work with the new investment account, navigate to the <guibutton>Investments</guibutton> view, 
  and choose the account you just created from the <guilabel>Select Account</guilabel> drop-down box.
</para>
</sect1>
            
<sect1 id="details.investments.securities">

            <title>Adding Investments to Your Account</title>
<para>
  To add individual Investments to your Investment Account, navigate to the <guibutton>Investments</guibutton> view, 
  and choose the account where the investment is held from the <guilabel>Select Account</guilabel> drop-down box.
  Ensure you are looking at the <guibutton>Investment Summary</guibutton> tab.
</para>
<para>
  Right-click the mouse in the empty space in the view.  
  This brings up the <guimenu>Investment Options</guimenu> context menu.  
  Choose <guimenuitem>New...</guimenuitem> from this menu.
  This launches the <guilabel>New Investment Wizard</guilabel> which you use to create your new Investment.
</para>
<para>
  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 &quot;RBC.NZ&quot;.  
</para>
</sect1>

<sect1 id="details.investments.summary">

            <title>Investment Summary Information</title>

<para>
  The Investment Summary tab lists your current holdings in this account, along with their price and value.
</para>
<para>
  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 <guimenu>Investment Options</guimenu> context menu.
</para>

<para>
	<screenshot>
	<mediaobject>
	<imageobject>
	<imagedata fileref="investments_summarytab.png" format="PNG" />
	</imageobject>
	<textobject>
	<phrase>Investments Summary Tab</phrase>
	</textobject>
	</mediaobject>
	</screenshot>
</para>

</sect1>

<sect1 id="details.investments.ledger"><title>Investment Transactions</title>
<para>
<screenshot>
	<screeninfo>Investment Transaction Form</screeninfo>
	<mediaobject>
	<imageobject>
	<imagedata fileref="investment-transactionform.png" format="PNG" />
	</imageobject>
	<textobject>
	<phrase>Investment Transaction Form</phrase>
	</textobject>
	</mediaobject>
</screenshot>
</para>
<para>
The investment ledger is almost the same as the <link linkend="details.ledgers">ledger</link> for other kinds of accounts.
Investment transactions have some additional elements:
</para>
<orderedlist numeration="upperalpha">
	<listitem><para>Activity</para></listitem>
	<listitem><para>Symbol Name</para></listitem>
	<listitem><para>Shares &amp; Price</para></listitem>
	<listitem><para>Fees</para></listitem>
	<listitem><para>Account</para></listitem>
</orderedlist>

<sect2><title>Activity</title>
<para>
The Activity for an investment transaction describes what action is happening to the stock.
The following activities are supported:
</para>

<itemizedlist>
	<listitem><para>Buy/Sell.  Use to record purchases or sales of individual investments.  This action requires an account to transfer the funds from/to.</para></listitem>
	<listitem><para>Dividend/Yield.  Also known as a &quot;Cash Dividend&quot;, 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.</para></listitem>
	<listitem><para>Reinvest Dividend.  This is a dividend where the proceeds are re-invested back into the investment.</para></listitem>
	<listitem><para>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.</para></listitem>
</itemizedlist>

</sect2>

<sect2><title>Symbol Name</title>
<para>
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.
</para>
</sect2>

<sect2><title>Shares, Price &amp; Total Amount</title>
<para>
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.
</para>
</sect2>

<sect2><title>Fees</title>
<para>
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.
</para>
</sect2>

<sect2><title>Account</title>
<para>
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.
</para>
</sect2>

</sect1>

<sect1 id="details.investments.foreign"><title>Working With Foreign Investments</title>
<para>
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.
</para>
<para>
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.
</para>
<para>
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.
</para>
<para>
<screenshot>
	<screeninfo>Currency Warning</screeninfo>
	<mediaobject>
	<imageobject>
	<imagedata fileref="investment-currencywarning.png" format="PNG" />
	</imageobject>
	<textobject>
	<phrase>Currency Warning</phrase>
	</textobject>
	</mediaobject>
</screenshot>
</para>
<para>
When you choose the brokerage account to fund the transfer, you'll be warned that it's in a different currency.
</para>
<para>
<screenshot>
	<screeninfo>Exchange Rate Editor</screeninfo>
	<mediaobject>
	<imageobject>
	<imagedata fileref="investment-exchangerateeditor.png" format="PNG" />
	</imageobject>
	<textobject>
	<phrase>Exchange Rate Editor</phrase>
	</textobject>
	</mediaobject>
</screenshot>
</para>
<para>
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 <link linkend="details.currencies.prices">Entering Prices Manually</link> for more information on the price dialog.
</para>
<para>
If you then switch over to the brokerage account, you will see the transaction in EUR, or 2,430.48 in this case.
</para>
</sect1>
<sect1 id="details.investments.prices"><title>Updating Prices</title>
<para>
You can enter prices for your investments using the same
<link linkend="details.currencies.prices">Price Editor</link> as used for currencies.  
Or you can fetch them electronically, using <link linkend="details.investments.onlinequotes">Online Price Quotes</link>.
</para>
</sect1>

<sect1 id="details.investments.onlinequotes">

						<title>Online Price Quotes</title>

<sect2><title>How Online Quotes Work</title>
<para>
	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.
</para>
<para>
	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.
</para>
<para>
	To find the trading symbol for a security supported by Yahoo, use the &quot;Symbol Lookup&quot; feature at http://finance.yahoo.com.
</para>
</sect2>

<sect2><title>Assigning a Quote Source</title>

<para>
	In order to get online price quotes, you first have to enable it for each investment or currency you want updated by setting a &quot;Online Quote Source&quot;.
	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.
</para>
<para>
	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 <guibutton>Edit</guibutton>.
	Choose the <guibutton>Quote Source</guibutton> tab.  
	Pick the appropriate source from the drop-down menu.
</para>
</sect2>

<sect2><title>Adjusting a quote</title>

<para>
	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.
</para>
<para>
	If this is the case for your online source, you can use the
	<guilabel>Factor</guilabel>
	field to enter an adjusting factor. For the above mentioned example
	the factor would be 0.01.
</para>
<para>
	The <guilabel>Factor</guilabel> field is only available if a
	<guibutton>Quote Source</guibutton> has been selected.
</para>
</sect2>

<sect2><title>Fetching Quotes</title>

<para>
	Typically, you will update the prices for all your investments and currencies at once. 
  Choose the   
  <menuchoice>
<guimenu>Tools</guimenu>
<guimenuitem>Update Stock and Currency Prices...</guimenuitem> </menuchoice> menu option to bring up the online price quotes dialog.  Press <guibutton>Update All</guibutton> to fetch quotes for all investments and currencies in your &kappname; file.
</para>
<para>
<screenshot>
	<screeninfo>Update Stock and Currency Prices</screeninfo>
	<mediaobject>
	<imageobject>
	<imagedata fileref="investment-onlineupdate.png" format="PNG" />
	</imageobject>
	<textobject>
	<phrase>Online Stock and Currency Price Update</phrase>
	</textobject>
	</mediaobject>
</screenshot>
</para>
</sect2>

<sect2><title>Editing or Adding Quote Sources</title>

<para>
	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.
</para>
<para>
	If you do feel up to the challenge, here's how it works.  
	The quote sources are contained in the settings dialog.  
	Choose <menuchoice><guimenu>Tools</guimenu><guimenuitem>Configure &kappname;</guimenuitem></menuchoice>.  
	From there, choose the <guilabel>Online Quotes</guilabel> 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 <guibutton>Update</guibutton> button before exiting the dialog.
	Your changes are not saved by default.
</para>
<para>
	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.
</para>
<para>
	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 &quot;file:/path/to/getquote.sh %1&quot;.
</para>
<para>
	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.  &quot;%m %d %y&quot; will parse &quot;December 31st, 2005&quot; as easily as &quot;12/31/05&quot;.  
	Two digit years are interpreted as being in the range of 1950-2049.
</para>
</sect2>
</sect1>
<sect1 id="details.investments.unimplemented"><title>Unimplemented Features</title>
<para>
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.
</para>
</sect1>
</chapter>