gnucash/src/doc/TODO-schedxactions

Author: jsled@asynchronous.org

Main Scheduled Transaction todo list
------------------------------------

##################################################
### Done
##################################################

X add the ...GetFreqStr() code for the complex composite FreqSpecs
X fix the ...GetNextInstance() code
X XMLv2 I/O
X need policy for start-dates in GNCFrequency
X fix GetNextInstance and GetInstanceAfter, mostly for composite FreqSpecs
  X also needs to deal with >28-mday values WRT last-occur date + multipliers
X Engine ...Init() functions should be private.
X would like "don't even tell me you instantiated it, just fscking do
  it!" option for non-manual-conf SXes

##################################################
### To-Do
### '.' = to-do, 'X' = done
##################################################


. FreqSpec.c
  . xaccFreqSpecGetFreqStr [display] needs to go away [?]

X create a template register
  X store account and amount data in kvp_frames.
  . find a way to list multiple registers for template transaction purposes.
    . this is a "normal" general ledger + a "stock" general ledger
    . this is going to be: a tabbed notebook in which the tabs contain
      the number of transactions the GL they hold contain.

. Hook into 'book data changed' save-on-exit decision 

. add a big calendar [gnome-pim?  evo?] to SXaction List/overview

. match existing transactions for long-time users
  . based off template-transaction data, some big existing-transaction
    scanning code.

. need "since-last-run" UI for instanatiation.
  X/O create transactions
    X numeric
    X formula
      X need variable fill-in UI...
        X re-use gnome-sheet code for a variable-binding table? -- ended up
          using GtkTable [for now?]
  X need way to expire/purge scheduled transactions which have no chance of
    being created [outside their end date; once-scheduled and past].
    X infrequent enough that a dialog should suffice.
  X need 'reminders' of upcoming scheduled transactions during since-last-run
    X Is it sufficient to look at the next instance of ea. transaction only?
      I think not... we probably want to look out until the transaction is
      outside the reminder range.
  . need some configuration for constantly-running GnuCash users of when to
    pop up the 'new scheduled transactions' dialog [option, time-of-day]
  . Should deal with "nothing-to-do" better [not even show up in the worst
    [read: no auto-notify/to-create/reminders] case].
  . Double-clicking on auto-create list should jump to transaction
    . register of first split?
  . double-clicking a reminder should [probably] move it up to the to-create
    list.
  X Easy UI way of moving through the SXes which need variable bindings.
    [This presently is: click "Ok" and the next clist row which needs
     bindings is selected.]
  . Need some way to defer to-create SXes.

. register mods
  . to see upcoming xactions, modifying future balance
  . to note which are "recurring"
    . the mozilla "reload" glyph is kinda neat...
  . Differently-colored "not-yet-created" entries for a configurable
    time window.
  . Context menus/sensitive toolbar button/menu item for creation of
    not-yet-created transactions.
  . The ability to turn a non-recurring transaction into a recurring one...
  . inactive cells
    . date
    . recn

. deal better with formulas in template transactions [real FormulaCell]
  . recognize purely numeric template transactions and balance at
    template-creation time.
  . balance transaction via symbolic math?

. GNCFrequency
  . initial-settings synchronization [start date, optionmenus]
    . only a couple left; which ones?

. backend support
  . PostgreSQL
  . others? 

. SX Creation...
  . Creation occurs due to a variety of circumstances:
    X GnuCash starts and hasn't been run in some length of time; the
      transactions which have "come due" since the last run are available for
      creation.
    . A user opens a register with future transactions in it; they manually
      force the creation of the [perhaps not immediately next [though this
      seems a bit weird]] one.
    . A user is reminded of something which hasn't come due, but will w/in a
      configurable amount of time, and thus they pay/create it.

. Configuration options...
  . Overall
    . Size of template register window
    . color of future register entries
    . conrad's desires
    . policy
      . create for N days in advance
      . show for N days in advance, create when come-due
    . defaults
      . create/show for 'N' days in advance
      . remind me 'M' days in advance
      . just create
      . notify when created
  . Per-SX
    . just create/notify
    . create/show
      . lead-time
    . reminder
      . lead-time



. [NOTES] Dealing with SX state-changes
  . Create-into-future vs. create-normal
    . into-future -> normal : no change; the last_occur date will be
      appropriate, and will catch up eventually [unless the have-been-created
      transactions should go away]
    . normal -> into-future : should create immed, or wait for user?
    . into-future [t_0] -> into_future [t_1]
  . frequency
    . in presence of create-into-future?
  . transaction
    . in presence of create-into-future?


##################################################
### Bugs
##################################################

. General
  . Date l10n.

. GNCFreqency
  . transitioning to a new tab doesn't correctly setup the agreement between
    the startdate and the page elements.
  . Example calendar month change isn't handled correctly/doesn't refresh the
    marks.
  . "Inappropriate FreqSpec type" on new-SX editing.
  . "new; weekly: click on day, click off day: GLib-CRITICAL **: file gdate.c: line 1236 (g_date_to_struct_tm): assertion `g_date_valid (d)' failed."

. Scheduled Transaction Editor
  . Can't click-out of the register
  . auto-shrink on window create [the register is too wide, leading to too
    much whitespace on the two top panels -- sometimes].
  . Size/space issues.
  . Un-selecting "End Date" leaves calendar widget sensitive
  . 'ESC' while editing template register causes window to go away [badly].
  . why does the accounts tab go crazy when we change the FreqSpec parameters?

. Scheduled Transaction List

. Since-last-run
  . any [horizontal] window size change height-grows the top/auto-create GL.
  X always goes one date past the instantiation date.
  . tab-order on variable-entry window isn't always correct.
  X credit and debit seem reversed at instantiation time...
    . this is fixed, but is the fix correct?

##################################################
### Enhancements
##################################################

. SX name should be default value for template transaction description
. loan/repayment SX's
  . integrate "Financial Calculator"
  . auto-determine number of occurances/end condition from liability
    account amount.
. SX since-last-run should be able to sort by Date [conditional on the dialog
  staying around].
. There probably wants to be a multi-month "example" View which the
  GNCFrequency can work with.
  . jalapeno/ben has some thoughts on this...
. Evolution calendar integ.
. Evolution To-Do list integ. [SX reminders]

========================================

Template Registers/Transactions

Template-option registers are used for users to enter the template
transaction to be created when the scheduled transaction comes due.
Most fields will be copied directly, but certain fields will need to
be modified upon instantiation, and the template version of these
transactions will need to contain the information necessary to do that
instiantion.  For some fields, this will be a derivable quantity, and
for others the user will need to be prompted.  This will show up
mostly for the amount of variable-amount transactions; perhaps the
amount is then derivable from some external source.  These amounts
will then be represented by a variable, a function, or a formula
including both.

Examples...

Verizon bill: "108.83 +- x"
	. x: tax amounts [user-input]
Power: "seasonal_util_gas( 'OAK_CA', '100 therms' ) + seasonal_util_elec( 'OAK_CA', '220 kwhrs' )"
	. seasonal_util_gas( loc, amt ): regional/seasonal power price
	. seasonal_util_elec( loc, amt ): regional/seasonal electricity price
Rent: 1900
Phone: "26"
Internet: "80 - 40 - 10" [3 splits]
Daily: "4 + 6 (+ 26)"
	. 4: cigarettes
	. 6: avg lunch
	. (opt) 20: wine
Gas: "regional_auto_gas( 'BERK_CA', 'premium', 14 gal +- 2 )"
	. regional_gas( loc, type, formula )
		. loc: location
		. type: subclass of gasoline
		. formula: formula to use for user-query
TROA: "220.14"

User-input

When user input is required for scheduled transaction instantiation,
we should have some sort of simple, spreadsheet-like UI for the entry
and verification of values.  This would allow the entry of all values
necessary for the formula to be calculated.

We also need a way to defer instantiation of a scheduled transaction
until the information can be obtained.

Example...

 type  | date       | formula           | variable | value |          total
+---------------------------------------------------------------------------+
| PG&E | 2001.04.12 | lookup(x) + lookup|      	   |   	   |   	    184     |
|---------------------------------------------------------------------------|
|      |	    |                  	|   x  	   |  142  |   	       	    |
|---------------------------------------------------------------------------|
|      |	    |		       	|   y  	   |   42  |	     	    |
|---------------------------------------------------------------------------|
| gas  | 2001.03.01 | cost/gal * gal   	|  	   |	   |	       	    |
|---------------------------------------------------------------------------|
|      |	    |			| cost/gal | 1.949 |	  14.27	    |
|---------------------------------------------------------------------------|
|      |	    |			| gal  	   | 12.32 |	       	    |
|---------------------------------------------------------------------------|
| gas  | 2001.03.12 | cost/gal * gal	|	   |	   |   	       	    |
|---------------------------------------------------------------------------|
|      |	    |		       	| cost/gal | 1.959 |	  15.39	    |
|---------------------------------------------------------------------------|
|      |	    |			| gal  	   | 13.43 |		    |
+---------------------------------------------------------------------------+

** Of course, "cost/gal" is going to be interpreted as division; perhaps we
can a) not handle it or b) have a heuristic. :(

I believe this means we can use the existing gnc-sheet/register-style
thingy.

We probably want to defer the lookup-based stuff until
1.8/2.0/gnumatic-provided network backing for this.

Stocks/recurring share purchases can make use of this, as well.  The
idea is then, probably, that the user will have a fixed amount with
which to buy as many shares as possible; the num-shares, then, is a
formula based on a lookup at the given time [the share price],
involving the function FLOOR.

It'd be nice if this formula could be either a simple infix syntax for
normal people, or a sexp for Schemers.

=================================================

Instantiation Notes
-------------------

<jsled> Wilddev, conrad:  Something that came out of Aaron's mail [see my reply to -devel] that I'd like your comment on:
<jsled> How do you intend to use scheduled transactions?
<jsled> Do you intend to use it to create things have should be in there since you last ran GnuCash?
<jsled> Or, do you intend to use it to create future transactions [perhaps a weeks worth] before they occur?
<jsled> Or, just primarily the former, but use the fact that the future transaction will be in the register to remind you to pay things, &c.?

<conrad> Personally, I'd be looking at future transactions as a reminder thing. But then, I run gnucash every day.
<jsled> conrad: Do you re-invoke it every day, or leave it running?
<conrad> I can see other people wanting case 1 though.
<conrad> I leave it running.
<jsled> conrad: Interesting.  You'd want some sort of "new-day" check/timer, then, to re-display the "create new transactions" dialog... or do you want to control it?
<jsled> the idea is that upon startup, if there are new transactions to create, the dialog will come up [configurable, but that should be the default].
<conrad> I think a further configurable sub-option should be "redisplay on change of day" (possibly with an "at time <blah> option?)")
<conrad> without that option, it will not do what I'm counting on it to do - remind my I'm supposed to pay my bills.
<jsled> Yup yup.


Summary...

conrad wants to use this to remind him to pay his bills.  He runs GnuCash
continuously, and thus wants an option to "pop-up on day change [at time
HH:MM]".  He's interested in seeing future transactions as well as what's
being created ATM.

-----

<Wilddev> There are 2 reasons to create scheduled transactions
<Wilddev> as a reminder you have to pay this bill by this day or I'll remind you until you do something, either skip me or mark me as paid, if the first I do nothing other than remind you, if the second I enter a transaction in the register
<Wilddev> and second
<Wilddev> as an actual transaction that goes into the register on a future date, ie I know that this money leaves my account in 2 days, so I want it to go in automatically on that day. If I leave gnucash running all the time, it'll wait until that day then enter the transaction
<Wilddev> as you can see the purpose of each is quite different
<jsled> Wilddev: Indeed...
<jsled> For the first, you're saying that reminders should start some number of days before the transaction is usually due/paid... and that there are two acknowledgements of that... 'remind me later' or 'here's the amount/create'.
<jsled> For the second, you're looking at ad-hoc once-scheduled transactions... which should go away immediately afterwards.
<Wilddev> yes, tho it would be nice to have when you actually get reminded configurable :)
<jsled> Wilddev: On a per-scheduled-transaction basis, I think.
<Wilddev> yup
<jsled> Okay... so this brings up something that isn't presently in the scheme at all: reminders.
<jsled> I think it's as simple as a "[ ] Remind me __ days in advance" element in the SXEditor, and the appropriate logic in the since-last-run code... 
<Wilddev> how often is the last run code 'run'?
<jsled> Wilddev: On startup, or when the timer [a-la conrad's requirement] goes off.
<Wilddev> yes that would work
<jsled> So the "since-last-run" dialog has three panes: 1) auto-created, notification requested.  2) To-create. 3) To-create-soon + reminders.
<Wilddev> that sounds good