View | Details | Raw Unified | Return to bug 39367
Collapse All | Expand All

(-)a/C4/SIP/ILS.pm (-54 / +524 lines)
Lines 47-62 my %supports = ( Link Here
47
    "renew all"             => 1,
47
    "renew all"             => 1,
48
);
48
);
49
49
50
=head1 Functions
51
52
=cut
53
54
=head2 new
55
56
Missing POD for new.
57
58
=cut
59
60
sub new {
50
sub new {
61
    my ( $class, $institution ) = @_;
51
    my ( $class, $institution ) = @_;
62
    my $type = ref($class) || $class;
52
    my $type = ref($class) || $class;
Lines 66-88 sub new { Link Here
66
    return bless $self, $type;
56
    return bless $self, $type;
67
}
57
}
68
58
69
=head2 find_patron
70
71
Missing POD for find_patron.
72
73
=cut
74
75
sub find_patron {
59
sub find_patron {
76
    my $self = shift;
60
    my $self = shift;
77
    return C4::SIP::ILS::Patron->new(@_);
61
    return C4::SIP::ILS::Patron->new(@_);
78
}
62
}
79
63
80
=head2 find_item
81
82
Missing POD for find_item.
83
84
=cut
85
86
sub find_item {
64
sub find_item {
87
    my $self = shift;
65
    my $self = shift;
88
    return C4::SIP::ILS::Item->new(@_);
66
    return C4::SIP::ILS::Item->new(@_);
Lines 93-126 sub institution { Link Here
93
    return $self->{institution}->{id};    # consider making this return the whole institution
71
    return $self->{institution}->{id};    # consider making this return the whole institution
94
}
72
}
95
73
96
=head2 institution_id
97
98
Missing POD for institution_id.
99
100
=cut
101
102
sub institution_id {
74
sub institution_id {
103
    my $self = shift;
75
    my $self = shift;
104
    return $self->{institution}->{id};
76
    return $self->{institution}->{id};
105
}
77
}
106
78
107
=head2 supports
108
109
Missing POD for supports.
110
111
=cut
112
113
sub supports {
79
sub supports {
114
    my ( $self, $op ) = @_;
80
    my ( $self, $op ) = @_;
115
    return ( exists( $supports{$op} ) && $supports{$op} );
81
    return ( exists( $supports{$op} ) && $supports{$op} );
116
}
82
}
117
83
118
=head2 check_inst_id
119
120
Missing POD for check_inst_id.
121
122
=cut
123
124
sub check_inst_id {
84
sub check_inst_id {
125
    my ( $self, $id, $whence ) = @_;
85
    my ( $self, $id, $whence ) = @_;
126
    if ( $id ne $self->{institution}->{id} ) {
86
    if ( $id ne $self->{institution}->{id} ) {
Lines 133-144 sub check_inst_id { Link Here
133
    }
93
    }
134
}
94
}
135
95
136
=head2 to_bool
137
138
Missing POD for to_bool.
139
140
=cut
141
142
sub to_bool {
96
sub to_bool {
143
    my $bool = shift;
97
    my $bool = shift;
144
98
Lines 180-186 sub offline_ok { Link Here
180
# returns a status opject that can be queried for the various bits
134
# returns a status opject that can be queried for the various bits
181
# of information that the protocol (SIP or NCIP) needs to generate
135
# of information that the protocol (SIP or NCIP) needs to generate
182
# the response.
136
# the response.
183
#
137
184
sub checkout {
138
sub checkout {
185
    my ( $self, $patron_id, $item_id, $sc_renew, $fee_ack, $account, $no_block_due_date ) = @_;
139
    my ( $self, $patron_id, $item_id, $sc_renew, $fee_ack, $account, $no_block_due_date ) = @_;
186
    my ( $patron, $item, $circ );
140
    my ( $patron, $item, $circ );
Lines 289-300 sub _ci_cardnumber_cmp { Link Here
289
243
290
# wrapper which allows above to be called for testing
244
# wrapper which allows above to be called for testing
291
245
292
=head2 test_cardnumber_compare
293
294
Missing POD for test_cardnumber_compare.
295
296
=cut
297
298
sub test_cardnumber_compare {
246
sub test_cardnumber_compare {
299
    my ( $self, $str1, $str2 ) = @_;
247
    my ( $self, $str1, $str2 ) = @_;
300
    return _ci_cardnumber_cmp( $str1, $str2 );
248
    return _ci_cardnumber_cmp( $str1, $str2 );
Lines 399-404 sub checkin { Link Here
399
347
400
# If the ILS caches patron information, this lets it free
348
# If the ILS caches patron information, this lets it free
401
# it up
349
# it up
350
402
sub end_patron_session {
351
sub end_patron_session {
403
    my ( $self, $patron_id ) = @_;
352
    my ( $self, $patron_id ) = @_;
404
353
Lines 534-539 sub cancel_hold { Link Here
534
483
535
# The patron and item id's can't be altered, but the
484
# The patron and item id's can't be altered, but the
536
# date, location, and type can.
485
# date, location, and type can.
486
537
sub alter_hold {
487
sub alter_hold {
538
    my (
488
    my (
539
        $self,        $patron_id,       $patron_pwd, $item_id, $title_id,
489
        $self,        $patron_id,       $patron_pwd, $item_id, $title_id,
Lines 680-684 sub renew_all { Link Here
680
}
630
}
681
631
682
1;
632
1;
683
__END__
684
633
634
=head1 NAME
635
636
ILS - Portability layer to interface between Open-SIP and ILS
637
638
=head1 SYNOPSIS
639
640
    use ILS;
641
642
    # Initialize connection between SIP and the ILS
643
    my $ils = new ILS (institution => 'Foo Public Library');
644
645
    # Basic object access methods
646
    $inst_name = $self->institution;
647
    $bool = $self->support($operation);
648
    $self->check_inst_id($inst_name, "error message");
649
650
    # Check to see if certain protocol options are permitted
651
    $bool = $self->checkout_ok;
652
    $bool = $self->checkin_ok;
653
    $bool = $self->status_update_ok;
654
    $bool = $self->offline_ok;
655
656
    $status = $ils->checkout($patron_id, $item_id, $sc_renew);
657
658
    $status = $ils->checkin($item_id, $trans_date, $return_date,
659
                            $current_loc, $item_props, $cancel);
660
661
    $status = $ils->end_patron_session($patron_id);
662
663
    $status = $ils->pay_fee($patron_id, $patron_pwd, $fee_amt,
664
                            $fee_type, $pay_type, $fee_id, $trans_id,
665
                            $currency);
666
667
    $status = $ils->add_hold($patron_id, $patron_pwd, $item_id,
668
			     $title_id, $expiry_date,
669
			     $pickup_locn, $hold_type, $fee_ack);
670
671
    $status = $ils->cancel_hold($patron_id, $patron_pwd,
672
                                $item_id, $title_id);
673
674
    $status = $ils->alter_hold($patron_id, $patron_pwd, $item_id,
675
                               $title_id, $expiry_date,
676
                               $pickup_locn, $hold_type,
677
                               $fee_ack);
678
679
    $status = $ils->renew($patron_id, $patron_pwd, $item_id,
680
                          $title_id, $no_block, $nb_due_date,
681
                          $third_party, $item_props, $fee_ack);
682
683
    $status = $ils->renew_all($patron_id, $patron_pwd, $fee_ack);
684
685
=head1 INTRODUCTION
686
687
The ILS module defines a basic portability layer between the SIP
688
server and the rest of the integrated library system.  It is the
689
responsibility of the ILS vendor to implement the functions
690
defined by this interface.  This allows the SIP server to be
691
reasonably portable between ILS systems (of course, we won't know
692
exactly I<how> portable the interface is until it's been used by
693
a second ILS.
694
695
Because no business logic is embedded in the SIP server code
696
itself, the SIP protocol handler functions do almost nothing
697
except decode the network messages and pass the parameters to the
698
ILS module or one of its submodules, C<ILS::Patron> and
699
C<ILS::Item>.  The SIP protocol query messages (Patron
700
Information, or Item Status, for example), are implemented within
701
the SIP server code by fetching a Patron, or Item, record and
702
then retrieving the relevant information from that record.  See
703
L<ILS::Patron> and L<ILS::Item> for the details.
704
705
=head1 INITIALIZATION
706
707
The first thing the SIP server does, after a terminal has
708
successfully logged in, is initialize the ILS module by calling
709
710
    $ils = new ILS $institution
711
712
where C<$institution> is a hash ( institution => 'Foo Public Library' )
713
describing the institution to which the terminal belongs.
714
In general, this will be the single institution that the ILS supports,
715
but it may be that in a consortial setting, the SIP server may support
716
connecting to different ILSs based on the C<$institution> of the terminal.
717
718
=head1 BASIC OBJECT ACCESS AND PROTOCOL SUPPORT
719
720
The C<$ils> object supports a small set of simple access methods
721
and methods that allow the SIP server to determine if certain
722
protocol operations are permitted to the remote terminals.
723
724
=head2 C<$inst_name = $self-E<gt>institution;>
725
726
Returns the institution ID as a string, suitable for
727
incorporating into a SIP response message.
728
729
=head2 C<$bool = $self-E<gt>support($operation);>
730
731
Reports whether this ILS implementation supports certain
732
operations that are necessary to report information to the SIP
733
terminal. The argument C<$operation> is a string from this list:
734
735
=over
736
737
=item C<'magnetic media'>
738
739
Can the ILS properly report whether an item is (or contains)
740
magnetic media, such as a videotape or a book with a floppy disk?
741
742
=item C<'security inhibit'>
743
744
Is the ILS capable of directing the terminal to ignore the
745
security status of an item?
746
747
=item C<'offline operation'>
748
749
Does the ILS allow self-check units to operate when unconnected
750
to the ILS?  That is, can a self-check unit check out items to
751
patrons without checking the status of the items and patrons in
752
real time?
753
754
=back
755
756
=head2 C<$bool = $self-E<gt>checkout_ok;>
757
758
Are the self service terminals permitted to check items out to
759
patrons?
760
761
=head2 C<$bool = $self-E<gt>checkin_ok;>
762
763
Are the self service terminals permitted to check items in?
764
765
=head2 C<$bool = $self-E<gt>status_update_ok;>
766
767
Are the self service terminals permitted to update patron status
768
information.  For example, can terminals block patrons?
769
770
=head2 C<$bool = $self-E<gt>offline_ok>;
771
772
Are the self service terminals permitted to operate off-line.
773
That is, can they perform their core self service operations when
774
not in communication with the ILS?
775
776
=head1 THE TRANSACTIONS
777
778
In general, every protocol transaction that changes the status of
779
some ILS object (Patron or Item) has a corresponding C<ILS>
780
method.  Operations like C<Check In>, which are a function of
781
both a patron and an item are C<ILS> functions, while others,
782
like C<Patron Status> or C<Item Status>, which only depend on one
783
type of object, are methods of the corresponding sub-module.
784
785
In the stub implementation provided with the SIP system, the
786
C<$status> objects returned by the various C<ILS> transactions
787
are objects that are subclasses of a virtual C<ILS::Transaction>
788
object, but this is not required of the SIP code, as long as the
789
status objects support the appropriate methods.
790
791
=head2 CORE TRANSACTION STATUS METHODS
792
793
The C<$status> objects returned by all transactions must support
794
the following common methods:
795
796
=over
797
798
=item C<ok>
799
800
Returns C<true> if the transaction was successful and C<false> if
801
not.  Other methods can be used to find out what went wrong.
802
803
=item C<item>
804
805
Returns an C<ILS::Item> object corresponding to the item with the
806
barcode C<$item_id>, or C<undef> if the barcode is invalid.
807
808
=item C<patron>
809
810
Returns a C<ILS::Patron> object corresponding to the patron with
811
the barcode C<$patron_id>, or C<undef> if the barcode is invalid
812
(ie, nonexistent, as opposed to "expired" or "delinquent").
813
814
=item C<screen_msg>
815
816
Optional. Returns a message that is to be displayed on the
817
terminal's screen.  Some self service terminals read the value of
818
this string and act based on it.  The configuration of the
819
terminal, and the ILS implementation of this method will have to
820
be coordinated.
821
822
=item C<print_line>
823
824
Optional.  Returns a message that is to be printed on the
825
terminal's receipt printer.  This message is distinct from the
826
basic transactional information that the terminal will be
827
printing anyway (such as, the basic checkout information like the
828
title and due date).
829
830
=back
831
832
=head2 C<$status = $ils-E<gt>checkout($patron_id, $item_id, $sc_renew)>
833
834
Check out (or possibly renew) item with barcode C<$item_id> to
835
the patron with barcode C<$patron_id>.  If C<$sc_renew> is true,
836
then the self-check terminal has been configured to allow
837
self-renewal of items, and the ILS may take this into account
838
when deciding how to handle the case where C<$item_id> is already
839
checked out to C<$patron_id>.
840
841
The C<$status> object returned by C<checkout> must support the
842
following methods:
843
844
=over
845
846
=item C<renewal_ok>
847
848
Is this transaction actually a renewal?  That is, did C<$patron_id>
849
already have C<$item_id> checked out?
850
851
=item C<desensitize>
852
853
Should the terminal desensitize the item?  This will be false for
854
magnetic media, like videocassettes, and for "in library" items
855
that are checked out to the patron, but not permitted to leave the
856
building.
857
858
=item C<security_inhibit>
859
860
Should self checkout unit ignore the security status of this
861
item?
862
863
This method will only be used if
864
865
    $ils->supports('security inhibit')
866
867
returns C<true>.
868
869
=item C<fee_amount>
870
871
If there is a fee associated with the use of C<$item_id>, then
872
this method should return the amount of the fee, otherwise it
873
should return zero.  See also the C<sip_currency> and
874
C<sip_fee_type> methods.
875
876
=item C<sip_currency>
877
878
The ISO currency code for the currency in which the fee
879
associated with this item is denominated.  For example, 'USD' or
880
'CAD'.
881
882
=item C<sip_fee_type>
883
884
A code indicating the type of fee associated with this item.  See
885
the table in the protocol specification for the complete list of
886
standard values that this function can return.
887
888
=back
889
890
=head2 C<$status = $ils-E<gt>checkin($item_id, $trans_date, $return_date, $current_loc, $item_props, $cancel)>
891
892
Check in item identified by barcode C<$item_id>.  This
893
transaction took place at time C<$trans_date> and was effective
894
C<$return_date> (to allow for backdating of items to when the
895
branch closed, for example). The self check unit which received
896
the item is located at C<$current_loc>, and the item has
897
properties C<$item_props>.  The parameters C<$current_loc> and
898
C<$item_props> are opaque strings passed from the self service
899
unit to the ILS untranslated.  The configuration of the terminal,
900
and the ILS implementation of this method will have to be
901
coordinated.
902
903
The C<$status> object returned by the C<checkin> operation must
904
support the following methods:
905
906
=over
907
908
=item C<resensitize>
909
910
Does the item need to be resensitized by the self check unit?
911
912
=item C<alert>
913
914
Should the self check unit generate an audible alert to notify
915
staff that the item has been returned?
916
917
=item C<sort_bin>
918
919
Certain self checkin units provide for automated sorting of the
920
returned items.  This function returns the bin number into which
921
the received item should be placed.  This function may return the
922
empty string, or C<undef>, to indicate that no sort bin has been
923
specified.
924
925
=back
926
927
=head2 C<($status, $screen_msg, $print_line) = $ils-E<gt>end_patron_session($patron_id)>
928
929
This function informs the ILS that the current patron's session
930
has ended.  This allows the ILS to free up any internal state
931
that it may be preserving between messages from the self check
932
unit.  The function returns a boolean C<$status>, where C<true>
933
indicates success, and two strings: a screen message to display
934
on the self check unit's console, and a print line to be printed
935
on the unit's receipt printer.
936
937
=head2 C<$status = $ils-E<gt>pay_fee($patron_id, $patron_pwd, $fee_amt, $fee_type, $pay_type, $fee_id, $trans_id, $currency)>
938
939
Reports that the self check terminal handled fee payment from
940
patron C<$patron_id> (who has password C<$patron_pwd>, which is
941
an optional parameter).  The other parameters are:
942
943
=over
944
945
=item C<$fee_amt>
946
947
The amount of the fee.
948
949
=item C<$fee_type>
950
951
The type of fee, according a table in the SIP protocol
952
specification.
953
954
=item C<$pay_type>
955
956
The payment method.  Defined in the SIP protocol specification.
957
958
=item C<$fee_id>
959
960
Optional. Identifies which particular fee was paid.  This
961
identifier would have been sent from the ILS to the Self Check
962
unit by a previous "Patron Information Response" message.
963
964
=item C<$trans_id>
965
966
Optional. A transaction identifier set by the payment device.
967
This should be recorded by the ILS for financial tracking
968
purposes.
969
970
=item C<$currency>
971
972
An ISO currency code indicating the currency in which the fee was
973
paid.
974
975
=back
976
977
The status object returned by the C<pay_fee> must support the
978
following methods:
979
980
=over
981
982
=item C<transaction_id>
983
984
Transaction identifier of the transaction.  This parallels the
985
optional C<$trans_id> sent from the terminal to the ILS.  This
986
may return an empty string.
987
988
=back
989
990
=head2 C<$status = $ils-E<gt>add_hold($patron_id, $patron_pwd, $item_id, $title_id, $expiry_date, $pickup_locn, $hold_type, $fee_ack);>
991
992
Places a hold for C<$patron_id> (optionally, with password
993
C<$patron_pwd>) on the item described by either C<$item_id> or
994
C<$title_id>. The other parameters are:
995
996
=over
997
998
=item C<$expiry_date>
999
1000
The date on which the hold should be cancelled.  This date is a
1001
SIP protocol standard format timestamp:
1002
1003
    YYYYMMDDZZZZHHMMSS
1004
1005
where the 'Z' characters indicate spaces.
1006
1007
=item C<$pickup_location>
1008
1009
The location at which the patron wishes to pick up the item when
1010
it's available.  The configuration of the terminal, and the ILS
1011
implementation of this parameter will have to be coordinated.
1012
1013
=item C<$hold_type>
1014
1015
The type of hold being placed: any copy, a specific copy, any
1016
copy from a particular branch or location.  See the SIP protocol
1017
specification for the exact values that this parameter might
1018
take.
1019
1020
=item C<$fee_ack>
1021
1022
Boolean.  If true, the patron has acknowleged that she is willing
1023
to pay the fee associated with placing a hold on this item.  If
1024
C<$fee_ack> is false, then the ILS should refuse to place the
1025
hold.
1026
1027
=back
1028
1029
=head2 C<$status = $ils-E<gt>cancel_hold($patron_id, $patron_pwd, $item_id, $title_id);>
1030
1031
Cancel a hold placed by C<$patron_id> for the item identified by
1032
C<$item_id> or C<$title_id>.  The patron password C<$patron_pwd>
1033
may be C<undef>, if it was not provided by the terminal.
1034
1035
=head2 C<$status = $ils-E<gt>alter_hold($patron_id, $patron_pwd, $item_id, $title_id, $expiry_date, $pickup_locn, $hold_type, $fee_ack);>
1036
1037
The C<$status> object returned by C<$ils-E<gt>add_hold>,
1038
C<$ils-E<gt>cancel_hold>, and C<$ils-E<gt>alter_hold> must all
1039
support the same methods:
1040
1041
=over
1042
1043
=item C<expiration_date>
1044
1045
Returns the expiry date for the placed hold, in seconds since the
1046
epoch.
1047
1048
=item C<queue_position>
1049
1050
Returns the new hold's place in the queue of outstanding holds.
1051
1052
=item C<pickup_location>
1053
1054
Returns the location code for the pickup location.
1055
1056
=back
1057
1058
=head2 C<$status = $ils-E<gt>renew($patron_id, $patron_pwd, $item_id, $title_id, $no_block, $nb_due_date, $third_party, $item_props, $fee_ack);>
1059
1060
Renew the item identified by C<$item_id> or C<$title_id>, as
1061
requested by C<$patron_id> (with password C<$patron_pwd>).  The
1062
item has the properties C<$item_props> associated with it.
1063
1064
If the patron renewed the item while the terminal was
1065
disconnected from the net, then it is a C<$no_block> transaction,
1066
and the due date assigned by the terminal, and reported to the
1067
patron was C<$nb_due_date> (so we have to honor it).
1068
1069
If there is a fee associated with renewing the item, and the
1070
patron has agreed to pay the fee, then C<$fee_ack> will be
1071
C<'Y'>.
1072
1073
If C<$third_party> is C<'Y'> and the book is not checked out to
1074
C<$patron_id>, but to some other person, then this is a
1075
third-party renewal; the item should be renewed for the person to
1076
whom it is checked out, rather than checking it out to
1077
C<$patron_id>, or the renewal should fail.
1078
1079
The C<$status> object returned by C<$ils-E<gt>renew> must support
1080
the following methods:
1081
1082
=over
1083
1084
=item C<renewal_ok>
1085
1086
Boolean.  If C<renewal_ok> is true, then the item was already
1087
checked out to the patron, so it is being renewed.  If
1088
C<renewal_ok> is false, then the patron did not already have the
1089
item checked out.
1090
1091
NOTE: HOW IS THIS USED IN PRACTICE?
1092
1093
=item C<desensitize>, C<security_inhibit>, C<fee_amount>, C<sip_currency>, C<sip_fee_type>, C<transaction_id>
1094
1095
See C<$ils-E<gt>checkout> for these methods.
1096
1097
=back
1098
1099
=head2 C<$status = $ils-E<gt>renew_all($patron_id, $patron_pwd, $fee_ack);>
1100
1101
Renew all items checked out by C<$patron_id> (with password
1102
C<$patron_pwd>).  If the patron has agreed to pay any fees
1103
associated with this transaction, then C<$fee_ack> will be
1104
C<'Y'>.
1105
1106
The C<$status> object must support the following methods:
1107
1108
=over
1109
1110
=item C<renewed>
1111
1112
Returns a list of the C<$item_id>s of the items that were renewed.
1113
1114
=item C<unrenewed>
1115
1116
Returns a list of the C<$item_id>s of the items that were not renewed.
1117
1118
=item C<new>
1119
1120
Missing POD for new.
1121
1122
=item C<find_patron>
1123
1124
Missing POD for find_patron.
1125
1126
=item C<institution>
1127
1128
Missing POD for institution.
1129
1130
=item C<institution_id>
1131
1132
Missing POD for institution_id.
1133
1134
=item C<supports>
1135
1136
Missing POD for supports.
1137
1138
=item C<check_inst_id>
1139
1140
Missing POD for check_inst_id.
1141
1142
=item C<find_item>
1143
1144
Missing POD for find_item.
1145
1146
=item C<test_cardnumber_compare>
1147
1148
Missing POD for test_cardnumber_compare.
1149
1150
=item C<to_bool>
1151
1152
Missing POD for to_bool.
1153
1154
=back
(-)a/C4/SIP/ILS.pod (-485 lines)
Lines 1-485 Link Here
1
=head1 NAME
2
3
ILS - Portability layer to interface between Open-SIP and ILS
4
5
=head1 SYNOPSIS
6
7
    use ILS;
8
9
    # Initialize connection between SIP and the ILS
10
    my $ils = new ILS (institution => 'Foo Public Library');
11
12
    # Basic object access methods
13
    $inst_name = $self->institution;
14
    $bool = $self->support($operation);
15
    $self->check_inst_id($inst_name, "error message");
16
17
    # Check to see if certain protocol options are permitted
18
    $bool = $self->checkout_ok;
19
    $bool = $self->checkin_ok;
20
    $bool = $self->status_update_ok;
21
    $bool = $self->offline_ok;
22
23
    $status = $ils->checkout($patron_id, $item_id, $sc_renew);
24
25
    $status = $ils->checkin($item_id, $trans_date, $return_date,
26
                            $current_loc, $item_props, $cancel);
27
28
    $status = $ils->end_patron_session($patron_id);
29
30
    $status = $ils->pay_fee($patron_id, $patron_pwd, $fee_amt,
31
                            $fee_type, $pay_type, $fee_id, $trans_id,
32
                            $currency);
33
34
    $status = $ils->add_hold($patron_id, $patron_pwd, $item_id,
35
			     $title_id, $expiry_date,
36
			     $pickup_locn, $hold_type, $fee_ack);
37
38
    $status = $ils->cancel_hold($patron_id, $patron_pwd,
39
                                $item_id, $title_id);
40
41
    $status = $ils->alter_hold($patron_id, $patron_pwd, $item_id,
42
                               $title_id, $expiry_date,
43
                               $pickup_locn, $hold_type,
44
                               $fee_ack);
45
46
    $status = $ils->renew($patron_id, $patron_pwd, $item_id,
47
                          $title_id, $no_block, $nb_due_date,
48
                          $third_party, $item_props, $fee_ack);
49
50
    $status = $ils->renew_all($patron_id, $patron_pwd, $fee_ack);
51
52
=head1 INTRODUCTION
53
54
The ILS module defines a basic portability layer between the SIP
55
server and the rest of the integrated library system.  It is the
56
responsibility of the ILS vendor to implement the functions
57
defined by this interface.  This allows the SIP server to be
58
reasonably portable between ILS systems (of course, we won't know
59
exactly I<how> portable the interface is until it's been used by
60
a second ILS.
61
62
Because no business logic is embedded in the SIP server code
63
itself, the SIP protocol handler functions do almost nothing
64
except decode the network messages and pass the parameters to the
65
ILS module or one of its submodules, C<ILS::Patron> and
66
C<ILS::Item>.  The SIP protocol query messages (Patron
67
Information, or Item Status, for example), are implemented within
68
the SIP server code by fetching a Patron, or Item, record and
69
then retrieving the relevant information from that record.  See
70
L<ILS::Patron> and L<ILS::Item> for the details.
71
72
=head1 INITIALIZATION
73
74
The first thing the SIP server does, after a terminal has
75
successfully logged in, is initialize the ILS module by calling
76
77
    $ils = new ILS $institution
78
79
where C<$institution> is a hash ( institution => 'Foo Public Library' )
80
describing the institution to which the terminal belongs.
81
In general, this will be the single institution that the ILS supports,
82
but it may be that in a consortial setting, the SIP server may support
83
connecting to different ILSs based on the C<$institution> of the terminal.
84
85
=head1 BASIC OBJECT ACCESS AND PROTOCOL SUPPORT
86
87
The C<$ils> object supports a small set of simple access methods
88
and methods that allow the SIP server to determine if certain
89
protocol operations are permitted to the remote terminals.
90
91
=head2 C<$inst_name = $self-E<gt>institution;>
92
93
Returns the institution ID as a string, suitable for
94
incorporating into a SIP response message.
95
96
=head2 C<$bool = $self-E<gt>support($operation);>
97
98
Reports whether this ILS implementation supports certain
99
operations that are necessary to report information to the SIP
100
terminal. The argument C<$operation> is a string from this list:
101
102
=over
103
104
=item C<'magnetic media'>
105
106
Can the ILS properly report whether an item is (or contains)
107
magnetic media, such as a videotape or a book with a floppy disk?
108
109
=item C<'security inhibit'>
110
111
Is the ILS capable of directing the terminal to ignore the
112
security status of an item?
113
114
=item C<'offline operation'>
115
116
Does the ILS allow self-check units to operate when unconnected
117
to the ILS?  That is, can a self-check unit check out items to
118
patrons without checking the status of the items and patrons in
119
real time?
120
121
=back
122
123
=head2 C<$bool = $self-E<gt>checkout_ok;>
124
125
Are the self service terminals permitted to check items out to
126
patrons?
127
128
=head2 C<$bool = $self-E<gt>checkin_ok;>
129
130
Are the self service terminals permitted to check items in?
131
132
=head2 C<$bool = $self-E<gt>status_update_ok;>
133
134
Are the self service terminals permitted to update patron status
135
information.  For example, can terminals block patrons?
136
137
=head2 C<$bool = $self-E<gt>offline_ok>;
138
139
Are the self service terminals permitted to operate off-line.
140
That is, can they perform their core self service operations when
141
not in communication with the ILS?
142
143
=head1 THE TRANSACTIONS
144
145
In general, every protocol transaction that changes the status of
146
some ILS object (Patron or Item) has a corresponding C<ILS>
147
method.  Operations like C<Check In>, which are a function of
148
both a patron and an item are C<ILS> functions, while others,
149
like C<Patron Status> or C<Item Status>, which only depend on one
150
type of object, are methods of the corresponding sub-module.
151
152
In the stub implementation provided with the SIP system, the
153
C<$status> objects returned by the various C<ILS> transactions
154
are objects that are subclasses of a virtual C<ILS::Transaction>
155
object, but this is not required of the SIP code, as long as the
156
status objects support the appropriate methods.
157
158
=head2 CORE TRANSACTION STATUS METHODS
159
160
The C<$status> objects returned by all transactions must support
161
the following common methods:
162
163
=over 
164
165
=item C<ok>
166
167
Returns C<true> if the transaction was successful and C<false> if
168
not.  Other methods can be used to find out what went wrong.
169
170
=item C<item>
171
172
Returns an C<ILS::Item> object corresponding to the item with the
173
barcode C<$item_id>, or C<undef> if the barcode is invalid.
174
175
=item C<patron>
176
177
Returns a C<ILS::Patron> object corresponding to the patron with
178
the barcode C<$patron_id>, or C<undef> if the barcode is invalid
179
(ie, nonexistent, as opposed to "expired" or "delinquent").
180
181
=item C<screen_msg>
182
183
Optional. Returns a message that is to be displayed on the
184
terminal's screen.  Some self service terminals read the value of
185
this string and act based on it.  The configuration of the
186
terminal, and the ILS implementation of this method will have to
187
be coordinated.
188
189
=item C<print_line>
190
191
Optional.  Returns a message that is to be printed on the
192
terminal's receipt printer.  This message is distinct from the
193
basic transactional information that the terminal will be
194
printing anyway (such as, the basic checkout information like the
195
title and due date).
196
197
=back
198
199
=head2 C<$status = $ils-E<gt>checkout($patron_id, $item_id, $sc_renew)>
200
201
Check out (or possibly renew) item with barcode C<$item_id> to
202
the patron with barcode C<$patron_id>.  If C<$sc_renew> is true,
203
then the self-check terminal has been configured to allow
204
self-renewal of items, and the ILS may take this into account
205
when deciding how to handle the case where C<$item_id> is already
206
checked out to C<$patron_id>.
207
208
The C<$status> object returned by C<checkout> must support the
209
following methods:
210
211
=over
212
213
=item C<renewal_ok>
214
215
Is this transaction actually a renewal?  That is, did C<$patron_id>
216
already have C<$item_id> checked out?
217
218
=item C<desensitize>
219
220
Should the terminal desensitize the item?  This will be false for
221
magnetic media, like videocassettes, and for "in library" items
222
that are checked out to the patron, but not permitted to leave the
223
building.
224
225
=item C<security_inhibit>
226
227
Should self checkout unit ignore the security status of this
228
item?
229
230
This method will only be used if
231
232
    $ils->supports('security inhibit')
233
234
returns C<true>.
235
236
=item C<fee_amount>
237
238
If there is a fee associated with the use of C<$item_id>, then
239
this method should return the amount of the fee, otherwise it
240
should return zero.  See also the C<sip_currency> and
241
C<sip_fee_type> methods.
242
243
=item C<sip_currency>
244
245
The ISO currency code for the currency in which the fee
246
associated with this item is denominated.  For example, 'USD' or
247
'CAD'.
248
249
=item C<sip_fee_type>
250
251
A code indicating the type of fee associated with this item.  See
252
the table in the protocol specification for the complete list of
253
standard values that this function can return.
254
255
=back
256
257
=head2 C<$status = $ils-E<gt>checkin($item_id, $trans_date, $return_date, $current_loc, $item_props, $cancel)>
258
259
Check in item identified by barcode C<$item_id>.  This
260
transaction took place at time C<$trans_date> and was effective
261
C<$return_date> (to allow for backdating of items to when the
262
branch closed, for example). The self check unit which received
263
the item is located at C<$current_loc>, and the item has
264
properties C<$item_props>.  The parameters C<$current_loc> and
265
C<$item_props> are opaque strings passed from the self service
266
unit to the ILS untranslated.  The configuration of the terminal,
267
and the ILS implementation of this method will have to be
268
coordinated.
269
270
The C<$status> object returned by the C<checkin> operation must
271
support the following methods:
272
273
=over
274
275
=item C<resensitize>
276
277
Does the item need to be resensitized by the self check unit?
278
279
=item C<alert>
280
281
Should the self check unit generate an audible alert to notify
282
staff that the item has been returned?
283
284
=item C<sort_bin>
285
286
Certain self checkin units provide for automated sorting of the
287
returned items.  This function returns the bin number into which
288
the received item should be placed.  This function may return the
289
empty string, or C<undef>, to indicate that no sort bin has been
290
specified.
291
292
=back
293
294
=head2 C<($status, $screen_msg, $print_line) = $ils-E<gt>end_patron_session($patron_id)>
295
296
This function informs the ILS that the current patron's session
297
has ended.  This allows the ILS to free up any internal state
298
that it may be preserving between messages from the self check
299
unit.  The function returns a boolean C<$status>, where C<true>
300
indicates success, and two strings: a screen message to display
301
on the self check unit's console, and a print line to be printed
302
on the unit's receipt printer.
303
304
=head2 C<$status = $ils-E<gt>pay_fee($patron_id, $patron_pwd, $fee_amt, $fee_type, $pay_type, $fee_id, $trans_id, $currency)>
305
306
Reports that the self check terminal handled fee payment from
307
patron C<$patron_id> (who has password C<$patron_pwd>, which is
308
an optional parameter).  The other parameters are:
309
310
=over
311
312
=item C<$fee_amt>
313
314
The amount of the fee.
315
316
=item C<$fee_type>
317
318
The type of fee, according a table in the SIP protocol
319
specification.
320
321
=item C<$pay_type>
322
323
The payment method.  Defined in the SIP protocol specification.
324
325
=item C<$fee_id>
326
327
Optional. Identifies which particular fee was paid.  This
328
identifier would have been sent from the ILS to the Self Check
329
unit by a previous "Patron Information Response" message.
330
331
=item C<$trans_id>
332
333
Optional. A transaction identifier set by the payment device.
334
This should be recorded by the ILS for financial tracking
335
purposes.
336
337
=item C<$currency>
338
339
An ISO currency code indicating the currency in which the fee was
340
paid.
341
342
=back
343
344
The status object returned by the C<pay_fee> must support the
345
following methods:
346
347
=over
348
349
=item C<transaction_id>
350
351
Transaction identifier of the transaction.  This parallels the
352
optional C<$trans_id> sent from the terminal to the ILS.  This
353
may return an empty string.
354
355
=back
356
357
=head2 C<$status = $ils-E<gt>add_hold($patron_id, $patron_pwd, $item_id, $title_id, $expiry_date, $pickup_locn, $hold_type, $fee_ack);>
358
359
Places a hold for C<$patron_id> (optionally, with password
360
C<$patron_pwd>) on the item described by either C<$item_id> or
361
C<$title_id>. The other parameters are:
362
363
=over
364
365
=item C<$expiry_date>
366
367
The date on which the hold should be cancelled.  This date is a
368
SIP protocol standard format timestamp:
369
370
    YYYYMMDDZZZZHHMMSS
371
372
where the 'Z' characters indicate spaces.
373
374
=item C<$pickup_location>
375
376
The location at which the patron wishes to pick up the item when
377
it's available.  The configuration of the terminal, and the ILS
378
implementation of this parameter will have to be coordinated.
379
380
=item C<$hold_type>
381
382
The type of hold being placed: any copy, a specific copy, any
383
copy from a particular branch or location.  See the SIP protocol
384
specification for the exact values that this parameter might
385
take.
386
387
=item C<$fee_ack>
388
389
Boolean.  If true, the patron has acknowleged that she is willing
390
to pay the fee associated with placing a hold on this item.  If
391
C<$fee_ack> is false, then the ILS should refuse to place the
392
hold.
393
394
=back
395
396
=head2 C<$status = $ils-E<gt>cancel_hold($patron_id, $patron_pwd, $item_id, $title_id);>
397
398
Cancel a hold placed by C<$patron_id> for the item identified by
399
C<$item_id> or C<$title_id>.  The patron password C<$patron_pwd>
400
may be C<undef>, if it was not provided by the terminal.
401
402
=head2 C<$status = $ils-E<gt>alter_hold($patron_id, $patron_pwd, $item_id, $title_id, $expiry_date, $pickup_locn, $hold_type, $fee_ack);>
403
404
The C<$status> object returned by C<$ils-E<gt>add_hold>,
405
C<$ils-E<gt>cancel_hold>, and C<$ils-E<gt>alter_hold> must all
406
support the same methods:
407
408
=over
409
410
=item C<expiration_date>
411
412
Returns the expiry date for the placed hold, in seconds since the
413
epoch.
414
415
=item C<queue_position>
416
417
Returns the new hold's place in the queue of outstanding holds.
418
419
=item C<pickup_location>
420
421
Returns the location code for the pickup location.
422
423
=back
424
425
=head2 C<$status = $ils-E<gt>renew($patron_id, $patron_pwd, $item_id, $title_id, $no_block, $nb_due_date, $third_party, $item_props, $fee_ack);>
426
427
Renew the item identified by C<$item_id> or C<$title_id>, as
428
requested by C<$patron_id> (with password C<$patron_pwd>).  The
429
item has the properties C<$item_props> associated with it.
430
431
If the patron renewed the item while the terminal was
432
disconnected from the net, then it is a C<$no_block> transaction,
433
and the due date assigned by the terminal, and reported to the
434
patron was C<$nb_due_date> (so we have to honor it).
435
436
If there is a fee associated with renewing the item, and the
437
patron has agreed to pay the fee, then C<$fee_ack> will be
438
C<'Y'>.
439
440
If C<$third_party> is C<'Y'> and the book is not checked out to
441
C<$patron_id>, but to some other person, then this is a
442
third-party renewal; the item should be renewed for the person to
443
whom it is checked out, rather than checking it out to
444
C<$patron_id>, or the renewal should fail.
445
446
The C<$status> object returned by C<$ils-E<gt>renew> must support
447
the following methods:
448
449
=over
450
451
=item C<renewal_ok>
452
453
Boolean.  If C<renewal_ok> is true, then the item was already
454
checked out to the patron, so it is being renewed.  If
455
C<renewal_ok> is false, then the patron did not already have the
456
item checked out.
457
458
NOTE: HOW IS THIS USED IN PRACTICE?
459
460
=item C<desensitize>, C<security_inhibit>, C<fee_amount>, C<sip_currency>, C<sip_fee_type>, C<transaction_id>
461
462
See C<$ils-E<gt>checkout> for these methods.
463
464
=back
465
466
=head2 C<$status = $ils-E<gt>renew_all($patron_id, $patron_pwd, $fee_ack);>
467
468
Renew all items checked out by C<$patron_id> (with password
469
C<$patron_pwd>).  If the patron has agreed to pay any fees
470
associated with this transaction, then C<$fee_ack> will be
471
C<'Y'>.
472
473
The C<$status> object must support the following methods:
474
475
=over
476
477
=item C<renewed>
478
479
Returns a list of the C<$item_id>s of the items that were renewed.
480
481
=item C<unrenewed>
482
483
Returns a list of the C<$item_id>s of the items that were not renewed.
484
485
=back
(-)a/C4/SIP/ILS/Item.pm (-1 / +232 lines)
Lines 586-590 sub format { Link Here
586
}
586
}
587
587
588
1;
588
1;
589
__END__
590
589
590
=head1 NAME
591
592
ILS::Item - Portable Item status object class for SIP
593
594
=head1 SYNOPSIS
595
596
	use ILS;
597
	use ILS::Item;
598
599
	# Look up item based on item_id
600
	my $item = new ILS::Item $item_id;
601
602
	# Basic object access methods
603
    $item_id    = $item->id;
604
    $title      = $item->title_id;
605
    $media_type = $item->sip_media_type;
606
    $bool       = $item->magnetic_media;
607
    $locn       = $item->permanent_location;
608
    $locn       = $item->current_location;
609
    $props      = $item->sip_item_props;
610
    $owner      = $item->owner;
611
    $str        = $item->sip_circulation_status;
612
    $bool       = $item->available;
613
    @hold_queue = $item->hold_queue;
614
    $pos        = $item->hold_queue_position($patron_id);
615
    $due        = $item->due_date;
616
    $pickup     = $item->hold_pickup_date;
617
    $recall     = $item->recall_date;
618
    $fee        = $item->fee;
619
    $currency   = $item->fee_currency;
620
    $type       = $item->sip_fee_type;
621
    $mark       = $item->sip_security_marker;
622
    $msg        = $item->screen_msg;
623
    $msg        = $item->print_line;
624
625
    # Operations on items
626
    $status = $item->status_update($item_props);
627
628
=head1 DESCRIPTION
629
630
An C<ILS::Item> object holds the information necessary to
631
circulate an item in the library's collection.  It does not need
632
to be a complete bibliographic description of the item; merely
633
basic human-appropriate identifying information is necessary
634
(that is, not the barcode, but just a title, and maybe author).
635
636
For the most part, C<ILS::Item>s are not operated on directly,
637
but are passed to C<ILS> methods as part of a transaction.  That
638
is, rather than having an item check itself in:
639
640
	$item->checkin;
641
642
the code tells the ILS that the item has returned:
643
644
	$ils->checkin($item_id);
645
646
Similarly, patron's don't check things out (a la,
647
C<$patron-E<gt>checkout($item)>), but the ILS checks items out to
648
patrons.  This means that the methods that are defined for items
649
are, almost exclusively, methods to retrieve information about
650
the state of the item.
651
652
=over
653
654
=item C<$item_id = $item-E<gt>id>
655
656
Return the item ID, or barcode, of C<$item>.
657
658
=item C<$title = $item-E<gt>title_id>
659
660
Return the title, or some other human-relevant description, of
661
the item.
662
663
=item C<$media_type = $item-E<gt>media_type>
664
665
Return the SIP-defined media type of the item.  The specification
666
provides the following definitions:
667
668
	000 Other
669
	001 Book
670
	002 Magazine
671
	003 Bound journal
672
	004 Audio tape
673
	005 Video tape
674
	006 CD/CDROM
675
	007 Diskette
676
	008 Book with diskette
677
	009 Book with CD
678
	010 Book with audio tape
679
680
The SIP server does not use the media type code to alter its
681
behavior at all; it merely passes it through to the self-service
682
terminal.  In particular, it does not set indicators related to
683
whether an item is magnetic, or whether it should be
684
desensitized, based on this return type.  The
685
C<$item-E<gt>magnetic_media> method will be used for that purpose.
686
687
=item C<magnetic_media>
688
689
Is the item some form of magnetic media (eg, a video or a book
690
with an accompanying floppy)?  This method will not be called
691
unless
692
693
    $ils->supports('magnetic media')
694
695
returns C<true>.
696
697
If this method is defined, it is assumed to return either C<true>
698
or C<false> for every item.  If the magnetic media indication is
699
not supported by the ILS, then the SIP server will indicate that
700
all items are 'Unknown'.
701
702
=item C<$locn = $item-E<gt>permanent_location>
703
704
Where does this item normally reside?  The protocol specification
705
is not clear on whether this is the item's "home branch", or a
706
location code within the branch, merely stating that it is, "The
707
location where an item is normally stored after being checked
708
in."
709
710
=item C<$locn = $item-E<gt>current_location>
711
712
According to the protocol, "[T]he current location of the item.
713
[A checkin terminal] could set this field to the ... system
714
terminal location on a Checkin message."
715
716
=item C<$props = $item-E<gt>sip_item_props>
717
718
Returns "item properties" associated with the item.  This is an
719
(optional) opaque string that is passed between the self-service
720
terminals and the ILS.  It can be set by the terminal, and should
721
be stored in the ILS if it is.
722
723
=item C<$owner = $item-E<gt>owner>
724
725
The spec says, "This field might contain the name of the
726
institution or library that owns the item."
727
728
=item C<$str = $item-E<gt>sip_circulation_status>
729
730
Returns a two-character string describing the circulation status
731
of the item, as defined in the specification:
732
733
	01 Other
734
	02 On order
735
	03 Available
736
	04 Charged
737
	05 Charged; not to be recalled until earliest recall date
738
	06 In process
739
	07 Recalled
740
	08 Waiting on hold shelf
741
	09 Waiting to be re-shelved
742
	10 In transit between library locations
743
	11 Claimed returned
744
	12 Lost
745
	13 Missing
746
747
=item C<$bool = $item-E<gt>available>
748
749
Is the item available?  That is, not checked out, and not on the
750
hold shelf?
751
752
=item C<@hold_queue = $item-E<gt>hold_queue>
753
754
Returns a list of the C<$patron_id>s of the patrons that have
755
outstanding holds on the item.
756
757
=item C<$pos = $item-E<gt>hold_queue_position($patron_id)>
758
759
Returns the location of C<$patron_id> in the hold queue for the
760
item, with '1' indicating the next person to receive the item.  A
761
return status of '0' indicates that C<$patron_id> does not have a
762
hold on the item.
763
764
=item C<$date = $item-E<gt>recall_date>
765
=item C<$date = $item-E<gt>hold_pickup_date>
766
767
These functions all return the corresponding date as a standard
768
SIP-format timestamp:
769
770
	YYYYMMDDZZZZHHMMSS
771
772
Where the C<'Z'> characters indicate spaces.
773
774
=item C<$date = $item-E<gt>due_date>
775
776
Returns the date the item is due.  The format for this timestamp
777
is not defined by the specification, but it should be something
778
simple for a human reader to understand.
779
780
=item C<$fee = $item-E<gt>fee>
781
782
The amount of the fee associated with borrowing this item.
783
784
=item C<$currency = $item-E<gt>fee_currency>
785
786
The currency in which the fee type above is denominated.  This
787
field is the ISO standard 4217 three-character currency code.  It
788
is highly unlikely that many systems will denominate fees in more
789
than one currency, however.
790
791
=item C<$type = $item-E<gt>sip_fee_type>
792
793
The type of fee being charged, as defined by the SIP protocol
794
specification:
795
796
	01 Other/unknown
797
	02 Administrative
798
	03 Damage
799
	04 Overdue
800
	05 Processing
801
	06 Rental
802
	07 Replacement
803
	08 Computer access charge
804
	09 Hold fee
805
806
=item C<$mark = $item-E<gt>sip_security_marker>
807
808
The type of security system with which the item is tagged:
809
810
	00 Other
811
	01 None
812
	02 3M Tattle-tape
813
	03 3M Whisper tape
814
815
=item C<$msg = $item-E<gt>screen_msg>
816
817
=item C<$msg = $item-E<gt>print_line>
818
819
The usual suspects.
820
821
=back
(-)a/C4/SIP/ILS/Item.pod (-232 lines)
Lines 1-232 Link Here
1
=head1 NAME
2
3
ILS::Item - Portable Item status object class for SIP
4
5
=head1 SYNOPSIS
6
7
	use ILS;
8
	use ILS::Item;
9
10
	# Look up item based on item_id
11
	my $item = new ILS::Item $item_id;
12
13
	# Basic object access methods
14
    $item_id    = $item->id;
15
    $title      = $item->title_id;
16
    $media_type = $item->sip_media_type;
17
    $bool       = $item->magnetic_media;
18
    $locn       = $item->permanent_location;
19
    $locn       = $item->current_location;
20
    $props      = $item->sip_item_props;
21
    $owner      = $item->owner;
22
    $str        = $item->sip_circulation_status;
23
    $bool       = $item->available;
24
    @hold_queue = $item->hold_queue;
25
    $pos        = $item->hold_queue_position($patron_id);
26
    $due        = $item->due_date;
27
    $pickup     = $item->hold_pickup_date;
28
    $recall     = $item->recall_date;
29
    $fee        = $item->fee;
30
    $currency   = $item->fee_currency;
31
    $type       = $item->sip_fee_type;
32
    $mark       = $item->sip_security_marker;
33
    $msg        = $item->screen_msg;
34
    $msg        = $item->print_line;
35
36
    # Operations on items
37
    $status = $item->status_update($item_props);
38
39
=head1 DESCRIPTION
40
41
An C<ILS::Item> object holds the information necessary to
42
circulate an item in the library's collection.  It does not need
43
to be a complete bibliographic description of the item; merely
44
basic human-appropriate identifying information is necessary
45
(that is, not the barcode, but just a title, and maybe author).
46
47
For the most part, C<ILS::Item>s are not operated on directly,
48
but are passed to C<ILS> methods as part of a transaction.  That
49
is, rather than having an item check itself in:
50
51
	$item->checkin;
52
53
the code tells the ILS that the item has returned:
54
55
	$ils->checkin($item_id);
56
57
Similarly, patron's don't check things out (a la,
58
C<$patron-E<gt>checkout($item)>), but the ILS checks items out to
59
patrons.  This means that the methods that are defined for items
60
are, almost exclusively, methods to retrieve information about
61
the state of the item.
62
63
=over
64
65
=item C<$item_id = $item-E<gt>id>
66
67
Return the item ID, or barcode, of C<$item>.
68
69
=item C<$title = $item-E<gt>title_id>
70
71
Return the title, or some other human-relevant description, of
72
the item.
73
74
=item C<$media_type = $item-E<gt>media_type>
75
76
Return the SIP-defined media type of the item.  The specification
77
provides the following definitions:
78
79
	000 Other
80
	001 Book
81
	002 Magazine
82
	003 Bound journal
83
	004 Audio tape
84
	005 Video tape
85
	006 CD/CDROM
86
	007 Diskette
87
	008 Book with diskette
88
	009 Book with CD
89
	010 Book with audio tape
90
91
The SIP server does not use the media type code to alter its
92
behavior at all; it merely passes it through to the self-service
93
terminal.  In particular, it does not set indicators related to
94
whether an item is magnetic, or whether it should be
95
desensitized, based on this return type.  The
96
C<$item-E<gt>magnetic_media> method will be used for that purpose.
97
98
=item C<magnetic_media>
99
100
Is the item some form of magnetic media (eg, a video or a book
101
with an accompanying floppy)?  This method will not be called
102
unless 
103
104
    $ils->supports('magnetic media')
105
106
returns C<true>.
107
108
If this method is defined, it is assumed to return either C<true>
109
or C<false> for every item.  If the magnetic media indication is
110
not supported by the ILS, then the SIP server will indicate that
111
all items are 'Unknown'.
112
113
=item C<$locn = $item-E<gt>permanent_location>
114
115
Where does this item normally reside?  The protocol specification
116
is not clear on whether this is the item's "home branch", or a
117
location code within the branch, merely stating that it is, "The
118
location where an item is normally stored after being checked
119
in."
120
121
=item C<$locn = $item-E<gt>current_location>
122
123
According to the protocol, "[T]he current location of the item.
124
[A checkin terminal] could set this field to the ... system
125
terminal location on a Checkin message."
126
127
=item C<$props = $item-E<gt>sip_item_props>
128
129
Returns "item properties" associated with the item.  This is an
130
(optional) opaque string that is passed between the self-service
131
terminals and the ILS.  It can be set by the terminal, and should
132
be stored in the ILS if it is.
133
134
=item C<$owner = $item-E<gt>owner>
135
136
The spec says, "This field might contain the name of the
137
institution or library that owns the item."
138
139
=item C<$str = $item-E<gt>sip_circulation_status>
140
141
Returns a two-character string describing the circulation status
142
of the item, as defined in the specification:
143
144
	01 Other
145
	02 On order
146
	03 Available
147
	04 Charged
148
	05 Charged; not to be recalled until earliest recall date
149
	06 In process
150
	07 Recalled
151
	08 Waiting on hold shelf
152
	09 Waiting to be re-shelved
153
	10 In transit between library locations
154
	11 Claimed returned
155
	12 Lost
156
	13 Missing
157
158
=item C<$bool = $item-E<gt>available>
159
160
Is the item available?  That is, not checked out, and not on the
161
hold shelf?
162
163
=item C<@hold_queue = $item-E<gt>hold_queue>
164
165
Returns a list of the C<$patron_id>s of the patrons that have
166
outstanding holds on the item.
167
168
=item C<$pos = $item-E<gt>hold_queue_position($patron_id)>
169
170
Returns the location of C<$patron_id> in the hold queue for the
171
item, with '1' indicating the next person to receive the item.  A
172
return status of '0' indicates that C<$patron_id> does not have a
173
hold on the item.
174
175
=item C<$date = $item-E<gt>recall_date>
176
=item C<$date = $item-E<gt>hold_pickup_date>
177
178
These functions all return the corresponding date as a standard
179
SIP-format timestamp:
180
181
	YYYYMMDDZZZZHHMMSS
182
183
Where the C<'Z'> characters indicate spaces.
184
185
=item C<$date = $item-E<gt>due_date>
186
187
Returns the date the item is due.  The format for this timestamp
188
is not defined by the specification, but it should be something
189
simple for a human reader to understand.
190
191
=item C<$fee = $item-E<gt>fee>
192
193
The amount of the fee associated with borrowing this item.
194
195
=item C<$currency = $item-E<gt>fee_currency>
196
197
The currency in which the fee type above is denominated.  This
198
field is the ISO standard 4217 three-character currency code.  It
199
is highly unlikely that many systems will denominate fees in more
200
than one currency, however.
201
202
=item C<$type = $item-E<gt>sip_fee_type>
203
204
The type of fee being charged, as defined by the SIP protocol
205
specification:
206
207
	01 Other/unknown
208
	02 Administrative
209
	03 Damage
210
	04 Overdue
211
	05 Processing
212
	06 Rental
213
	07 Replacement
214
	08 Computer access charge
215
	09 Hold fee
216
217
=item C<$mark = $item-E<gt>sip_security_marker>
218
219
The type of security system with which the item is tagged:
220
221
	00 Other
222
	01 None
223
	02 3M Tattle-tape
224
	03 3M Whisper tape
225
226
=item C<$msg = $item-E<gt>screen_msg>
227
228
=item C<$msg = $item-E<gt>print_line>
229
230
The usual suspects.
231
232
=back
(-)a/C4/SIP/ILS/Patron.pm (+212 lines)
Lines 923-925 __END__ Link Here
923
    {itemlist}    ref-to-array: list of available items
923
    {itemlist}    ref-to-array: list of available items
924
924
925
=cut
925
=cut
926
927
928
=head1 NAME
929
930
ILS::Patron - Portable Patron status object class for SIP
931
932
=head1 DESCRIPTION
933
934
A C<ILS::Patron> object holds information about a patron that's
935
used by self service terminals to authenticate and authorize a patron,
936
and to display information about the patron's borrowing activity.
937
938
=head1 SYNOPSIS
939
940
	use ILS;
941
	use ILS::Patron;
942
943
	# Look up patron based on patron_id
944
	my $patron = new ILS::Patron $patron_id
945
946
	# Basic object access methods
947
	$patron_id = $patron->id;
948
	$str = $patron->name;
949
	$str = $patron->address;
950
	$str = $patron->email_addr;
951
	$str = $patron->home_phone;
952
	$str = $patron->sip_birthdate;
953
	$str = $patron->ptype;
954
	$str = $patron->language;
955
	$str = $patron->password;
956
	$str = $patron->check_password($password);
957
	$str = $patron->currency;
958
	$str = $patron->screen_msg;
959
	$str = $patron->print_line;
960
961
	# Check patron permissions
962
	$bool = $patron->charge_ok;
963
	$bool = $patron->renew_ok;
964
	$bool = $patron->recall_ok;
965
	$bool = $patron->hold_ok;
966
	$bool = $patron->card_lost;
967
	$bool = $patron->too_many_charged;
968
	$bool = $patron->too_many_overdue;
969
	$bool = $patron->too_many_renewal;
970
	$bool = $patron->too_many_claim_return;
971
	$bool = $patron->too_many_lost( $server );
972
	$bool = $patron->excessive_fines;
973
	$bool = $patron->excessive_fees;
974
	$bool = $patron->too_many_billed;
975
976
	# Patron borrowing activity
977
	$num = $patron->recall_overdue;
978
	$num = $patron->fee_amount;
979
	$bool = $patron->drop_hold($item_id);
980
	@holds = $patron->hold_items($start, $end);
981
	@items = $patron->overdue_items($start, $end);
982
	@items = $patron->charged_items($start, $end);
983
	@items = $patron->fine_items($start, $end);
984
	@items = $patron->recall_items($start, $end);
985
	@items = $patron->unavail_holds($start, $end);
986
987
	# Changing a patron's status
988
	$patron->block($card_retained, $blocked_msg);
989
	$patron->enable;
990
991
=head1 INITIALIZATION
992
993
A patron object is created by calling
994
995
	$patron = new ILS::Patron $patron_id;
996
997
where C<$patron_id> is the patron's barcode as received from the
998
self service terminal.  If the patron barcode is not registered,
999
then C<new> should return C<undef>.
1000
1001
=head1 BASIC OBJECT ACCESS METHODS
1002
1003
The following functions return the corresponding information
1004
about the given patron, or C<undef> if the information is
1005
unavailable.
1006
1007
	$patron_id = $patron-E<gt>id;
1008
	$str = $patron-E<gt>name;
1009
	$str = $patron-E<gt>address;
1010
	$str = $patron-E<gt>email_addr;
1011
	$str = $patron-E<gt>home_phone;
1012
1013
	$str = $patron-E<gt>screen_msg;
1014
	$str = $patron-E<gt>print_line;
1015
1016
If there are outstanding display messages associated with the
1017
patron, then these return the screen message and print line,
1018
respectively, as with the C<ILS> methods.
1019
1020
There are a few other object access methods that need a bit more
1021
explication however.
1022
1023
=head2 C<$str = $patron-E<gt>sip_birthdate;>
1024
1025
Returns the patron's birthday formatted according to the SIP
1026
specification:
1027
1028
	YYYYMMDD    HHMMSS
1029
1030
=head2 C<$str = $patron-E<gt>ptype;>
1031
1032
Returns the "patron type" of the patron.  This is not used by the
1033
SIP server code, but is passed through to the self service
1034
terminal (using the non-standard protocol field "PC").  Some self
1035
service terminals use the patron type in determining what level
1036
of service to provide (for example, Envisionware computer
1037
management software can be configured to filter internet access
1038
based on patron type).
1039
1040
=head2 C<$str = $patron-E<gt>language;>
1041
1042
A three-digit string encoding the patron's preferred language.
1043
The full list is defined in the SIP specification, but some of
1044
the important values are:
1045
1046
	000 Unknown (default)
1047
	001 English
1048
	002 French
1049
	008 Spanish
1050
	011 Canadian French
1051
	016 Arabic
1052
	019 Chinese
1053
	021 North American Spanish
1054
1055
=head2 C<$bool = $patron-E<gt>check_password($password);>
1056
1057
Returns C<true> if C<$patron>'s password is C<$password>.
1058
1059
=head2 C<$str = $patron-E<gt>currency;>
1060
1061
Returns the three character ISO 4217 currency code for the
1062
patron's preferred currency.
1063
1064
=head1 CHECKING PATRON PERMISSIONS
1065
1066
Most of the methods associated with Patrons are related to
1067
checking if they're authorized to perform various actions:
1068
1069
	$bool = $patron-E<gt>charge_ok;
1070
	$bool = $patron-E<gt>renew_ok;
1071
	$bool = $patron-E<gt>recall_ok;
1072
	$bool = $patron-E<gt>hold_ok;
1073
	$bool = $patron-E<gt>card_lost;
1074
	$bool = $patron-E<gt>recall_overdue;
1075
	$bool = $patron-E<gt>too_many_charged;
1076
	$bool = $patron-E<gt>too_many_overdue;
1077
	$bool = $patron-E<gt>too_many_renewal;
1078
	$bool = $patron-E<gt>too_many_claim_return;
1079
	$bool = $patron-E<gt>too_many_lost( $server );
1080
	$bool = $patron-E<gt>excessive_fines;
1081
	$bool = $patron-E<gt>excessive_fees;
1082
	$bool = $patron-E<gt>too_many_billed;
1083
1084
=head1 LISTS OF ITEMS ASSOCIATED WITH THE USER
1085
1086
The C<$patron> object provides a set of methods to find out
1087
information about various sets that are associated with the
1088
user.  All these methods take two optional parameters: C<$start>
1089
and C<$end>, which define a subset of the list of items to be
1090
returned (C<1> is the first item in the list).  The following
1091
methods all return a reference to a list of C<$item_id>s:
1092
1093
	$items = $patron-E<gt>hold_items($start, $end);
1094
	$items = $patron-E<gt>overdue_items($start, $end);
1095
	$items = $patron-E<gt>charged_items($start, $end);
1096
	$items = $patron-E<gt>recall_items($start, $end);
1097
	$items = $patron-E<gt>unavail_holds($start, $end);
1098
1099
It is also possible to retrieve an itemized list of the fines
1100
outstanding.  This method returns a reference to an itemized list
1101
of fines:
1102
1103
	$fines = $patron-E<gt>fine_items($start, $end);
1104
1105
=head1 PATRON BORROWING ACTIVITY
1106
1107
=head2 C<$num = $patron-E<gt>fee_amount;>
1108
1109
The total amount of fees and fines owed by the patron.
1110
1111
=head2 C<$bool = $patron-E<gt>drop_hold($item_id);>
1112
1113
Drops the hold that C<$patron> has placed on the item
1114
C<$item_id>.  Returns C<false> if the patron did not have a hold
1115
on the item, C<true> otherwise.
1116
1117
1118
1119
=head1 CHANGING A PATRON'S STATUS
1120
1121
=head2 C<$status = $ils-E<gt>block($card_retained, $blocked_card_msg);>
1122
1123
Block the account of the patron identified by C<$patron_id>.  If
1124
the self check unit captured the patron's card, then
1125
C<$card_retained> will be C<true>.  A message indicating why the
1126
card was retained will be provided by the parameter
1127
C<$blocked_card_msg>.
1128
1129
This function returns an C<ILS::Patron> object that has been
1130
updated to indicate that the patron's privileges have been
1131
blocked, or C<undef> if the patron ID is not valid.
1132
1133
=head2 C<$patron-E<gt>enable;>
1134
1135
Reenable the patron after she's been blocked.  This is a test
1136
function and will not normally be called by self-service
1137
terminals in production.
(-)a/C4/SIP/ILS/Patron.pod (-210 lines)
Lines 1-210 Link Here
1
=head1 NAME
2
3
ILS::Patron - Portable Patron status object class for SIP
4
5
=head1 DESCRIPTION
6
7
A C<ILS::Patron> object holds information about a patron that's
8
used by self service terminals to authenticate and authorize a patron,
9
and to display information about the patron's borrowing activity.
10
11
=head1 SYNOPSIS
12
13
	use ILS;
14
	use ILS::Patron;
15
16
	# Look up patron based on patron_id
17
	my $patron = new ILS::Patron $patron_id
18
19
	# Basic object access methods
20
	$patron_id = $patron->id;
21
	$str = $patron->name;
22
	$str = $patron->address;
23
	$str = $patron->email_addr;
24
	$str = $patron->home_phone;
25
	$str = $patron->sip_birthdate;	
26
	$str = $patron->ptype;
27
	$str = $patron->language;
28
	$str = $patron->password;
29
	$str = $patron->check_password($password);
30
	$str = $patron->currency;
31
	$str = $patron->screen_msg;
32
	$str = $patron->print_line;
33
34
	# Check patron permissions 
35
	$bool = $patron->charge_ok;
36
	$bool = $patron->renew_ok;
37
	$bool = $patron->recall_ok;
38
	$bool = $patron->hold_ok;
39
	$bool = $patron->card_lost;
40
	$bool = $patron->too_many_charged;
41
	$bool = $patron->too_many_overdue;
42
	$bool = $patron->too_many_renewal;
43
	$bool = $patron->too_many_claim_return;
44
	$bool = $patron->too_many_lost( $server );
45
	$bool = $patron->excessive_fines;
46
	$bool = $patron->excessive_fees;
47
	$bool = $patron->too_many_billed;
48
49
	# Patron borrowing activity
50
	$num = $patron->recall_overdue;
51
	$num = $patron->fee_amount;
52
	$bool = $patron->drop_hold($item_id);
53
	@holds = $patron->hold_items($start, $end);
54
	@items = $patron->overdue_items($start, $end);
55
	@items = $patron->charged_items($start, $end);
56
	@items = $patron->fine_items($start, $end);
57
	@items = $patron->recall_items($start, $end);
58
	@items = $patron->unavail_holds($start, $end);
59
60
	# Changing a patron's status
61
	$patron->block($card_retained, $blocked_msg);
62
	$patron->enable;
63
64
=head1 INITIALIZATION
65
66
A patron object is created by calling
67
68
	$patron = new ILS::Patron $patron_id;
69
70
where C<$patron_id> is the patron's barcode as received from the
71
self service terminal.  If the patron barcode is not registered,
72
then C<new> should return C<undef>.
73
74
=head1 BASIC OBJECT ACCESS METHODS
75
76
The following functions return the corresponding information
77
about the given patron, or C<undef> if the information is
78
unavailable.
79
80
	$patron_id = $patron-E<gt>id;
81
	$str = $patron-E<gt>name;
82
	$str = $patron-E<gt>address;
83
	$str = $patron-E<gt>email_addr;
84
	$str = $patron-E<gt>home_phone;
85
86
	$str = $patron-E<gt>screen_msg;
87
	$str = $patron-E<gt>print_line;
88
89
If there are outstanding display messages associated with the
90
patron, then these return the screen message and print line,
91
respectively, as with the C<ILS> methods.
92
93
There are a few other object access methods that need a bit more
94
explication however.
95
96
=head2 C<$str = $patron-E<gt>sip_birthdate;>
97
98
Returns the patron's birthday formatted according to the SIP
99
specification:
100
101
	YYYYMMDD    HHMMSS
102
103
=head2 C<$str = $patron-E<gt>ptype;>
104
105
Returns the "patron type" of the patron.  This is not used by the
106
SIP server code, but is passed through to the self service
107
terminal (using the non-standard protocol field "PC").  Some self
108
service terminals use the patron type in determining what level
109
of service to provide (for example, Envisionware computer
110
management software can be configured to filter internet access
111
based on patron type).
112
113
=head2 C<$str = $patron-E<gt>language;>
114
115
A three-digit string encoding the patron's preferred language.
116
The full list is defined in the SIP specification, but some of
117
the important values are:
118
119
	000 Unknown (default)
120
	001 English
121
	002 French
122
	008 Spanish
123
	011 Canadian French
124
	016 Arabic
125
	019 Chinese
126
	021 North American Spanish
127
128
=head2 C<$bool = $patron-E<gt>check_password($password);>
129
130
Returns C<true> if C<$patron>'s password is C<$password>.
131
132
=head2 C<$str = $patron-E<gt>currency;>
133
134
Returns the three character ISO 4217 currency code for the
135
patron's preferred currency.
136
137
=head1 CHECKING PATRON PERMISSIONS 
138
139
Most of the methods associated with Patrons are related to
140
checking if they're authorized to perform various actions:
141
142
	$bool = $patron-E<gt>charge_ok;
143
	$bool = $patron-E<gt>renew_ok;
144
	$bool = $patron-E<gt>recall_ok;
145
	$bool = $patron-E<gt>hold_ok;
146
	$bool = $patron-E<gt>card_lost;
147
	$bool = $patron-E<gt>recall_overdue;
148
	$bool = $patron-E<gt>too_many_charged;
149
	$bool = $patron-E<gt>too_many_overdue;
150
	$bool = $patron-E<gt>too_many_renewal;
151
	$bool = $patron-E<gt>too_many_claim_return;
152
	$bool = $patron-E<gt>too_many_lost( $server );
153
	$bool = $patron-E<gt>excessive_fines;
154
	$bool = $patron-E<gt>excessive_fees;
155
	$bool = $patron-E<gt>too_many_billed;
156
157
=head1 LISTS OF ITEMS ASSOCIATED WITH THE USER
158
159
The C<$patron> object provides a set of methods to find out
160
information about various sets that are associated with the
161
user.  All these methods take two optional parameters: C<$start>
162
and C<$end>, which define a subset of the list of items to be
163
returned (C<1> is the first item in the list).  The following
164
methods all return a reference to a list of C<$item_id>s:
165
166
	$items = $patron-E<gt>hold_items($start, $end);
167
	$items = $patron-E<gt>overdue_items($start, $end);
168
	$items = $patron-E<gt>charged_items($start, $end);
169
	$items = $patron-E<gt>recall_items($start, $end);
170
	$items = $patron-E<gt>unavail_holds($start, $end);
171
172
It is also possible to retrieve an itemized list of the fines
173
outstanding.  This method returns a reference to an itemized list
174
of fines:
175
176
	$fines = $patron-E<gt>fine_items($start, $end);
177
178
=head1 PATRON BORROWING ACTIVITY
179
180
=head2 C<$num = $patron-E<gt>fee_amount;>
181
182
The total amount of fees and fines owed by the patron.
183
184
=head2 C<$bool = $patron-E<gt>drop_hold($item_id);>
185
186
Drops the hold that C<$patron> has placed on the item
187
C<$item_id>.  Returns C<false> if the patron did not have a hold
188
on the item, C<true> otherwise.
189
190
191
192
=head1 CHANGING A PATRON'S STATUS
193
194
=head2 C<$status = $ils-E<gt>block($card_retained, $blocked_card_msg);>
195
196
Block the account of the patron identified by C<$patron_id>.  If
197
the self check unit captured the patron's card, then
198
C<$card_retained> will be C<true>.  A message indicating why the
199
card was retained will be provided by the parameter
200
C<$blocked_card_msg>.
201
202
This function returns an C<ILS::Patron> object that has been
203
updated to indicate that the patron's privileges have been
204
blocked, or C<undef> if the patron ID is not valid.
205
206
=head2 C<$patron-E<gt>enable;>
207
208
Reenable the patron after she's been blocked.  This is a test
209
function and will not normally be called by self-service
210
terminals in production.
(-)a/C4/SIP/Sip.pm (-1 / +6 lines)
Lines 48-53 our $field_delimiter = '|'; # Protocol Default Link Here
48
48
49
our $last_response = '';
49
our $last_response = '';
50
50
51
=head2 y_or_n
52
53
Missing POD for y_or_n.
54
55
=cut
56
51
=head2 timestamp
57
=head2 timestamp
52
58
53
Missing POD for timestamp.
59
Missing POD for timestamp.
54
- 

Return to bug 39367