[Koha] API for circulation interfaces

[Chris Cormack]

* Tonnesen Steve <tonnesen at cmsd.bc.ca> [010111 08:20]:
> 
> Here is a proposed list of functions necessary to generate arbitrary
> circulation interfaces.  Comments requested.
> 
> Is this an appropriate forum for programming discussion?
> 
I think so for now, if we start generating heavy traffic, we can start up a
koha-dev list or something og the like

> 
> 
> Program API for circulation interfaces:
> 
> ====================
> getpatroninformation
> ====================
> Subroutine returns a hash reference with all patron information.  Can be called
> with either borrowernumber or cardnumber.
> 
> ($env, $patroninformation) = getpatroninformation($env,$borrowernumber,$cardnumber)
> 
I think maybe this might need to return reference to a hash of flags also.
For example if the borrower owes a substantial amount of money, or a has a 
note on his/card a warning should be displayed. 
Depending on the flag different actions should be taken also.
The flags could be included in patroninformation though I guess, 
eg $patroninformation->{'flags'}=\%flags;

> 
> =============
> currentissues
> =============
> 
> Returns a hash reference (itemnumber => duedate)
> 
> ($env, $currentissues) = currentissues($env, $borrowernumber);
> 
> 
Yep seems fine

> ==================
> getiteminformation
> ==================
> 
> Subroutine returns a hash reference with all item information.  Can be called
> with either itemnumber or barcode.
> 
> ($env, $iteminformation) = getiteminformation($env,$itemnumber,$barcode)
> 
Looks good

> 
> ============
> findborrower
> ============
> 
> Subroutine returns an array reference containing a list of borrowernumbers that match $key.  $key could be a cardnumber or a partial last name.
> 
> ($env, $borrowernumber) = findborrower($env, $key)
> 
Ditto

> 
> =========
> issuebook
> =========
> 
> This subroutine may or may not generate additional questions that must be answered.
> 
> ($env, $itemnumber, $rejected, $question, $questionnumber, $defaultanswer, $responses) =
>     issuebook($env,$borrowernumber,$barcode)
> 
> Subroutine must handle errors, some that block issuing, some that must be
> approved before issuing.
> 
> If $rejected is not null, it will contain a message detailing the reason for
> rejection.  Possible responses are listed below, prepended with 'Error:'.
> Alternatively, $rejected may just be '-1' in which case the issue should be
> rejected with no message displayed to the user.  This might happen if the
> answer to a question resulted in a rejection.
> 
> Error: Invalid barcode _____
> Error: Invalid borrowernumber ____
> Error: Item is restricted  [$item->{'notforloan'}==1]
> Error: Item withdrawn [$item->{'withdrawn'}==1]
> Error: Restricted Item (and borrower not allowed to check out)
>     [$item->{'restricted'}==1]
> Error: Reference item not for loan [$item->{'itemtype'} eq 'REF']
>     [Circulation::Renewals::renewstatus]
> Error: Issued to this patron, no renewals. 
> 
> 
> If $question is not null, it will contain a YesNo question that should be
> asked.  $defaultanswer will contain 'Y' or 'N'.  $questionnumber will contain a
> unique integer for each question that might be asked.  Interface code will
> generate a hash reference ($responses) with the responsees to each question
> asked and then recall issuebook() until the issue is accepted or rejected.
> 
> Question: Already issued to this patron and reserved to ___, renew?  default N
> Question: Already issued to this patron, renew?
>     [$newdate=C4::Circulation::Renewals::renewbook()]
> Question: Already issued to patron ___, mark as returned?
>     [returnrecord()]
> 
> calculate any charges   [calc_charges()] and [createcharge()]
> 
> 
Yeah this looks like a good way to do it, i think that maybe we could pass
to issuebook the patroninformation, rather than the borrowernumber.
That way we wouldnt have to check certain flags again like the borrower
owing more than x dollars, which prohibits issues.
That is assuming that u call getpatroninformation before issuebook.
Just a thought.

> 
> ==========
> returnbook
> ==========
> 
> Subroutine for returning a book.  $message may contain an arbitrary message to display to the user (maybe should be an array reference for multiple messages?).
> 
> ($env, $itemnumber, $borrowernumber, $message, $overduefees) = returnbook($env,$barcode)
> 
> Message: Reserved for collection at branch _______
> Calculate any overdue fees (not in current Circulation code)
> 
> [UpdateStats]
> 
Hmm I think $message will need to be an array reference.
If an item has been marked as lost, and then is returned, maybe a message
might be wanted to alert the librarian to the fact that this was marked as a
lost item.
As well as the Reserve notice.


Looking good so far,
I think those are the main circulation functions.

In fact issuing and returning items are the only things you cant do with the
web interface.

The other things contained in circ like renewals, and payments are there
because of speed issues.
It would be good to build them into the API tho as well, whether ppl choose
to implement them in their circulation interface can be up to them.

Thanks for your work on this Steve,

Chris
-- 
Chris Cormack                                                       Programmer
025 500 789                                          Katipo Communications Ltd
chris at katipo.co.nz                                            www.katipo.co.nz