<<

NAME

C4::Members - Perl Module containing convenience functions for member handling

SYNOPSIS

use C4::Members;

DESCRIPTION

This module contains routines for adding, modifying and deleting members/patrons/borrowers

FUNCTIONS

GetMemberDetails

($borrower) = &GetMemberDetails($borrowernumber, $cardnumber);

Looks up a patron and returns information about him or her. If $borrowernumber is true (nonzero), &GetMemberDetails looks up the borrower by number; otherwise, it looks up the borrower by card number.

$borrower is a reference-to-hash whose keys are the fields of the borrowers table in the Koha database. In addition, $borrower->{flags} is a hash giving more detailed information about the patron. Its keys act as flags :

    if $borrower->{flags}->{LOST} {
        # Patron's card was reported lost
    }

If the state of a flag means that the patron should not be allowed to borrow any more books, then it will have a noissues key with a true value.

See patronflags for more details.

$borrower->{authflags} is a hash giving more detailed information about the top-level permissions flags set for the borrower. For example, if a user has the "editcatalogue" permission, $borrower->{authflags}->{editcatalogue} will exist and have the value "1".

patronflags

 $flags = &patronflags($patron);

This function is not exported.

The following will be set where applicable: $flags->{CHARGES}->{amount} Amount of debt $flags->{CHARGES}->{noissues} Set if debt amount >$5.00 (or syspref noissuescharge) $flags->{CHARGES}->{message} Message -- deprecated

 $flags->{CREDITS}->{amount}        Amount of credit
 $flags->{CREDITS}->{message}       Message -- deprecated

 $flags->{  GNA  }                  Patron has no valid address
 $flags->{  GNA  }->{noissues}      Set for each GNA
 $flags->{  GNA  }->{message}       "Borrower has no valid address" -- deprecated

 $flags->{ LOST  }                  Patron's card reported lost
 $flags->{ LOST  }->{noissues}      Set for each LOST
 $flags->{ LOST  }->{message}       Message -- deprecated

 $flags->{DBARRED}                  Set if patron debarred, no access
 $flags->{DBARRED}->{noissues}      Set for each DBARRED
 $flags->{DBARRED}->{message}       Message -- deprecated

 $flags->{ NOTES }
 $flags->{ NOTES }->{message}       The note itself.  NOT deprecated

 $flags->{ ODUES }                  Set if patron has overdue books.
 $flags->{ ODUES }->{message}       "Yes"  -- deprecated
 $flags->{ ODUES }->{itemlist}      ref-to-array: list of overdue books
 $flags->{ ODUES }->{itemlisttext}  Text list of overdue items -- deprecated

 $flags->{WAITING}                  Set if any of patron's reserves are available
 $flags->{WAITING}->{message}       Message -- deprecated
 $flags->{WAITING}->{itemlist}      ref-to-array: list of available items
$flags->{ODUES}->{itemlist} is a reference-to-array listing the overdue items. Its elements are references-to-hash, each describing an overdue item. The keys are selected fields from the issues, biblio, biblioitems, and items tables of the Koha database.
$flags->{ODUES}->{itemlisttext} is a string giving a text listing of the overdue items, one per line. Deprecated.
$flags->{WAITING}->{itemlist} is a reference-to-array listing the available items. Each element is a reference-to-hash whose keys are fields from the reserves table of the Koha database.

All the "message" fields that include language generated in this function are deprecated, because such strings belong properly in the display layer.

The "message" field that comes from the DB is OK.

GetMember

  $borrower = &GetMember(%information);

Retrieve the first patron record meeting on criteria listed in the %information hash, which should contain one or more pairs of borrowers column names and values, e.g.,

   $borrower = GetMember(borrowernumber => id);

&GetBorrower returns a reference-to-hash whose keys are the fields of the borrowers table in the Koha database.

FIXME: GetMember() is used throughout the code as a lookup on a unique key such as the borrowernumber, but this meaning is not enforced in the routine itself.

GetMemberRelatives

 @borrowernumbers = GetMemberRelatives($borrowernumber);

 C<GetMemberRelatives> returns a borrowersnumber's list of guarantor/guarantees of the member given in parameter

IsMemberBlocked

  my ($block_status, $count) = IsMemberBlocked( $borrowernumber );

Returns whether a patron is restricted or has overdue items that may result in a block of circulation privileges.

$block_status can have the following values:

1 if the patron is currently restricted, in which case $count is the expiration date (9999-12-31 for indefinite)

-1 if the patron has overdue items, in which case $count is the number of them

0 if the patron has no overdue items or outstanding fine days, in which case $count is 0

Existing active restrictions are checked before current overdue items.

GetMemberIssuesAndFines

  ($overdue_count, $issue_count, $total_fines) = &GetMemberIssuesAndFines($borrowernumber);

Returns aggregate data about items borrowed by the patron with the given borrowernumber.

&GetMemberIssuesAndFines returns a three-element array. $overdue_count is the number of overdue items the patron currently has borrowed. $issue_count is the number of books the patron currently has borrowed. $total_fines is the total fine currently due by the borrower.

columns

  my @columns = C4::Member::columns();

Returns an array of borrowers' table columns on success, and an empty array on failure.

ModMember

  my $success = ModMember(borrowernumber => $borrowernumber,
                                            [ field => value ]... );

Modify borrower's data. All date fields should ALREADY be in ISO format.

return : true on success, or false on failure

AddMember

  $borrowernumber = &AddMember(%borrower);

insert new borrower into table

(%borrower keys are database columns. Database columns could be different in different versions. Please look into database for correct column names.)

Returns the borrowernumber upon success

Returns as undef upon any db error without further processing

Check_Userid

    my $uniqueness = Check_Userid($userid,$borrowernumber);

    $borrowernumber is optional (i.e. it can contain a blank value). If $userid is passed with a blank $borrowernumber variable, the database will be checked for all instances of that userid (i.e. userid=? AND borrowernumber != '').

    If $borrowernumber is provided, the database will be checked for every instance of that userid coupled with a different borrower(number) than the one provided.

    return :
        0 for not unique (i.e. this $userid already exists)
        1 for unique (i.e. this $userid does not exist, or this $userid/$borrowernumber combination already exists)

Generate_Userid

    my $newuid = Generate_Userid($borrowernumber, $firstname, $surname);

    Generate a userid using the $surname and the $firstname (if there is a value in $firstname).

    $borrowernumber is optional (i.e. it can contain a blank value). A value is passed when generating a new userid for an existing borrower. When a new userid is created for a new borrower, a blank value is passed to this sub.

    return :
        new userid ($firstname.$surname if there is a $firstname, or $surname if there is no value in $firstname) plus offset (0 if the $newuid is unique, or a higher numeric value if Check_Userid finds an existing match for the $newuid in the database).

fixup_cardnumber

Warning: The caller is responsible for locking the members table in write mode, to avoid database corruption.

GetGuarantees

  ($num_children, $children_arrayref) = &GetGuarantees($parent_borrno);
  $child0_cardno = $children_arrayref->[0]{"cardnumber"};
  $child0_borrno = $children_arrayref->[0]{"borrowernumber"};

&GetGuarantees takes a borrower number (e.g., that of a patron with children) and looks up the borrowers who are guaranteed by that borrower (i.e., the patron's children).

&GetGuarantees returns two values: an integer giving the number of borrowers guaranteed by $parent_borrno, and a reference to an array of references to hash, which gives the actual results.

UpdateGuarantees

  &UpdateGuarantees($parent_borrno);

&UpdateGuarantees borrower data for an adult and updates all the guarantees with the modified information

GetPendingIssues

  my $issues = &GetPendingIssues(@borrowernumber);

Looks up what the patron with the given borrowernumber has borrowed.

&GetPendingIssues returns a reference-to-array where each element is a reference-to-hash; the keys are the fields from the issues, biblio, and items tables. The keys include biblioitems fields except marc and marcxml.

GetAllIssues

  $issues = &GetAllIssues($borrowernumber, $sortkey, $limit);

Looks up what the patron with the given borrowernumber has borrowed, and sorts the results.

$sortkey is the name of a field on which to sort the results. This should be the name of a field in the issues, biblio, biblioitems, or items table in the Koha database.

$limit is the maximum number of results to return.

&GetAllIssues an arrayref, $issues, of hashrefs, the keys of which are the fields from the issues, biblio, biblioitems, and items tables of the Koha database.

GetMemberAccountRecords

  ($total, $acctlines, $count) = &GetMemberAccountRecords($borrowernumber);

Looks up accounting data for the patron with the given borrowernumber.

&GetMemberAccountRecords returns a three-element array. $acctlines is a reference-to-array, where each element is a reference-to-hash; the keys are the fields of the accountlines table in the Koha database. $count is the number of elements in $acctlines. $total is the total amount outstanding for all of the account lines.

GetMemberAccountBalance

  ($total_balance, $non_issue_balance, $other_charges) = &GetMemberAccountBalance($borrowernumber);

Calculates amount immediately owing by the patron - non-issue charges. Based on GetMemberAccountRecords. Charges exempt from non-issue are: * Res (reserves) * Rent (rental) if RentalsInNoissuesCharge syspref is set to false * Manual invoices if ManInvInNoissuesCharge syspref is set to false

GetBorNotifyAcctRecord

  ($total, $acctlines, $count) = &GetBorNotifyAcctRecord($params,$notifyid);

Looks up accounting data for the patron with the given borrowernumber per file number.

&GetBorNotifyAcctRecord returns a three-element array. $acctlines is a reference-to-array, where each element is a reference-to-hash; the keys are the fields of the accountlines table in the Koha database. $count is the number of elements in $acctlines. $total is the total amount outstanding for all of the account lines.

checkuniquemember (OUEST-PROVENCE)

  ($result,$categorycode)  = &checkuniquemember($collectivity,$surname,$firstname,$dateofbirth);

Checks that a member exists or not in the database.

&result is nonzero (=exist) or 0 (=does not exist) &categorycode is from categorycode table &collectivity is 1 (= we add a collectivity) or 0 (= we add a physical member) &surname is the surname &firstname is the firstname (only if collectivity=0) &dateofbirth is the date of birth in ISO format (only if collectivity=0)

get_cardnumber_length

    my ($min, $max) = C4::Members::get_cardnumber_length()

Returns the minimum and maximum length for patron cardnumbers as determined by the CardnumberLength system preference, the BorrowerMandatoryField system preference, and the width of the database column.

getzipnamecity (OUEST-PROVENCE)

take all info from table city for the fields city and zip check for the name and the zip code of the city selected

getdcity (OUEST-PROVENCE)

recover cityid with city_name condition

GetFirstValidEmailAddress

  $email = GetFirstValidEmailAddress($borrowernumber);

Return the first valid email address for a borrower, given the borrowernumber. For now, the order is defined as email, emailpro, B_email. Returns the empty string if the borrower has no email addresses.

GetNoticeEmailAddress

  $email = GetNoticeEmailAddress($borrowernumber);

Return the email address of borrower used for notices, given the borrowernumber. Returns the empty string if no email address.

GetExpiryDate

  $expirydate = GetExpiryDate($categorycode, $dateenrolled);

Calculate expiry date given a categorycode and starting date. Date argument must be in ISO format. Return date is also in ISO format.

GetUpcomingMembershipExpires

  my $upcoming_mem_expires = GetUpcomingMembershipExpires();

GetborCatFromCatType

  ($codes_arrayref, $labels_hashref) = &GetborCatFromCatType();

Looks up the different types of borrowers in the database. Returns two elements: a reference-to-array, which lists the borrower category codes, and a reference-to-hash, which maps the borrower category codes to category descriptions.

GetBorrowercategory

  $hashref = &GetBorrowercategory($categorycode);

Given the borrower's category code, the function returns the corresponding data hashref for a comprehensive information display.

GetBorrowerCategorycode

    $categorycode = &GetBorrowerCategoryCode( $borrowernumber );

Given the borrowernumber, the function returns the corresponding categorycode

GetBorrowercategoryList

  $arrayref_hashref = &GetBorrowercategoryList;
If no category code provided, the function returns all the categories.

GetAge

  $dateofbirth,$date = &GetAge($date);

this function return the borrowers age with the value of dateofbirth

SetAge

  $borrower = C4::Members::SetAge($borrower, $datetimeduration);
  $borrower = C4::Members::SetAge($borrower, '0015-12-10');
  $borrower = C4::Members::SetAge($borrower, $datetimeduration, $datetime_reference);

  eval { $borrower = C4::Members::SetAge($borrower, '015-1-10'); };
  if ($@) {print $@;} #Catch a bad ISO Date or kill your script!

This function sets the borrower's dateofbirth to match the given age. Optionally relative to the given $datetime_reference.

@PARAM1 koha.borrowers-object @PARAM2 DateTime::Duration-object as the desired age OR a ISO 8601 Date. (To make the API more pleasant) @PARAM3 DateTime-object as the relative date, defaults to now(). RETURNS The given borrower reference @PARAM1. DIES If there was an error with the ISO Date handling.

GetCities

  $cityarrayref = GetCities();

  Returns an array_ref of the entries in the cities table
  If there are entries in the table an empty row is returned
  This is currently only used to populate a popup in memberentry

GetSortDetails (OUEST-PROVENCE)

  ($lib) = &GetSortDetails($category,$sortvalue);

Returns the authorized value details &$libreturn value of authorized value details &$sortvaluethis is the value of authorized value &$categorythis is the value of authorized value category

MoveMemberToDeleted

  $result = &MoveMemberToDeleted($borrowernumber);

Copy the record from borrowers to deletedborrowers table. The routine returns 1 for success, undef for failure.

DelMember

    DelMember($borrowernumber);

This function remove directly a borrower whitout writing it on deleteborrower. + Deletes reserves for the borrower

HandleDelBorrower

     HandleDelBorrower($borrower);

When a member is deleted (DelMember in Members.pm), you should call me first. This routine deletes/moves lists and entries for the deleted member/borrower. Lists owned by the borrower are deleted, but entries from the borrower to other lists are kept.

ExtendMemberSubscriptionTo (OUEST-PROVENCE)

    $date = ExtendMemberSubscriptionTo($borrowerid, $date);

Extending the subscription to a given date or to the expiry date calculated on ISO date. Returns ISO date.

GetTitles (OUEST-PROVENCE)

  ($borrowertitle)= &GetTitles();

Looks up the different title . Returns array with all borrowers title

GetPatronImage

    my ($imagedata, $dberror) = GetPatronImage($borrowernumber);

Returns the mimetype and binary image data of the image for the patron with the supplied borrowernumber.

PutPatronImage

    PutPatronImage($cardnumber, $mimetype, $imgfile);

Stores patron binary image data and mimetype in database. NOTE: This function is good for updating images as well as inserting new images in the database.

RmPatronImage

    my ($dberror) = RmPatronImage($borrowernumber);

Removes the image for the patron with the supplied borrowernumber.

GetHideLostItemsPreference

  $hidelostitemspref = &GetHideLostItemsPreference($borrowernumber);

Returns the HideLostItems preference for the patron category of the supplied borrowernumber &$hidelostitemsprefreturn value of function, 0 or 1

GetBorrowersToExpunge

  $borrowers = &GetBorrowersToExpunge(
      not_borrowed_since   => $not_borrowed_since,
      expired_before       => $expired_before,
      category_code        => $category_code,
      branchcode           => $branchcode
  );

  This function get all borrowers based on the given criteria.

GetBorrowersWhoHaveNeverBorrowed

  $results = &GetBorrowersWhoHaveNeverBorrowed

This function get all borrowers who have never borrowed.

$result is a ref to an array which all elements are a hasref.

GetBorrowersWithIssuesHistoryOlderThan

  $results = &GetBorrowersWithIssuesHistoryOlderThan($date)

this function get all borrowers who has an issue history older than $date given on input arg.

$result is a ref to an array which all elements are a hashref. This hashref is containt the number of time this borrowers has borrowed before $date and the borrowernumber.

GetBorrowersNamesAndLatestIssue

  $results = &GetBorrowersNamesAndLatestIssueList(@borrowernumbers)

this function get borrowers Names and surnames and Issue information.

@borrowernumbers is an array which all elements are borrowernumbers. This hashref is containt the number of time this borrowers has borrowed before $date and the borrowernumber.

ModPrivacy

  my $success = ModPrivacy( $borrowernumber, $privacy );

Update the privacy of a patron.

return : true on success, false on failure

AddMessage

  AddMessage( $borrowernumber, $message_type, $message, $branchcode );

Adds a message to the messages table for the given borrower.

Returns: True on success False on failure

GetMessages

  GetMessages( $borrowernumber, $type );

$type is message type, B for borrower, or L for Librarian. Empty type returns all messages of any type.

Returns all messages for the given borrowernumber

GetMessages

  GetMessagesCount( $borrowernumber, $type );

$type is message type, B for borrower, or L for Librarian. Empty type returns all messages of any type.

Returns the number of messages for the given borrowernumber

DeleteMessage

  DeleteMessage( $message_id );

IssueSlip

  IssueSlip($branchcode, $borrowernumber, $quickslip)

  Returns letter hash ( see C4::Letters::GetPreparedLetter )

  $quickslip is boolean, to indicate whether we want a quick slip

  IssueSlip populates ISSUESLIP and ISSUEQSLIP, and will make the following expansions:

  Both slips:

      <<branches.*>>
      <<borrowers.*>>

  ISSUESLIP:

      <checkedout>
         <<biblio.*>>
         <<items.*>>
         <<biblioitems.*>>
         <<issues.*>>
      </checkedout>

      <overdue>
         <<biblio.*>>
         <<items.*>>
         <<biblioitems.*>>
         <<issues.*>>
      </overdue>

      <news>
         <<opac_news.*>>
      </news>

  ISSUEQSLIP:

      <checkedout>
         <<biblio.*>>
         <<items.*>>
         <<biblioitems.*>>
         <<issues.*>>
      </checkedout>

  NOTE: Not all table fields are available, pleasee see GetPendingIssues for a list of available fields.

GetBorrowersWithEmail

    ([$borrnum,$userid], ...) = GetBorrowersWithEmail('me@example.com');

This gets a list of users and their basic details from their email address. As it's possible for multiple user to have the same email address, it provides you with all of them. If there is no userid for the user, there will be an undef there. An empty list will be returned if there are no matches.

AddMember_Opac

AddEnrolmentFeeIfNeeded

    AddEnrolmentFeeIfNeeded( $borrower->{categorycode}, $borrower->{borrowernumber} );

Add enrolment fee for a patron if needed.

HasOverdues

DeleteExpiredOpacRegistrations

    Delete accounts that haven't been upgraded from the 'temporary' category
    Returns the number of removed patrons

DeleteUnverifiedOpacRegistrations

    Delete all unverified self registrations in borrower_modifications,
    older than the specified number of days.

AUTHOR

Koha Team

<<