1 package C4::Members::Messaging;
3 # Copyright (C) 2008 LibLime
5 # This file is part of Koha.
7 # Koha is free software; you can redistribute it and/or modify it
8 # under the terms of the GNU General Public License as published by
9 # the Free Software Foundation; either version 3 of the License, or
10 # (at your option) any later version.
12 # Koha is distributed in the hope that it will be useful, but
13 # WITHOUT ANY WARRANTY; without even the implied warranty of
14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 # GNU General Public License for more details.
17 # You should have received a copy of the GNU General Public License
18 # along with Koha; if not, see <http://www.gnu.org/licenses>.
27 # set the version for version checking
28 $VERSION = 3.07.00.049;
33 C4::Members::Messaging - manage patron messaging preferences
37 use C4::Members::Messaging
41 This module lets you modify a patron's messaging preferences.
45 =head2 GetMessagingPreferences
47 my $preferences = C4::Members::Messaging::GetMessagingPreferences( { borrowernumber => $borrower->{'borrowernumber'},
48 message_name => 'DUE' } );
50 my $preferences = C4::Members::Messaging::GetMessagingPreferences( { categorycode => 'LIBRARY',
51 message_name => 'DUE' } );
53 returns: a hashref of messaging preferences for a borrower or patron category for a particlar message_name
55 Requires either a borrowernumber or a categorycode key, but not both.
59 sub GetMessagingPreferences {
62 return unless exists $params->{message_name};
63 return unless exists $params->{borrowernumber} xor exists $params->{categorycode}; # yes, xor
64 my $sql = <<'END_SQL';
65 SELECT borrower_message_preferences.*,
66 borrower_message_transport_preferences.message_transport_type,
67 message_attributes.message_name,
68 message_attributes.takes_days,
69 message_transports.is_digest,
70 message_transports.letter_module,
71 message_transports.letter_code
72 FROM borrower_message_preferences
73 LEFT JOIN borrower_message_transport_preferences
74 ON borrower_message_transport_preferences.borrower_message_preference_id = borrower_message_preferences.borrower_message_preference_id
75 LEFT JOIN message_attributes
76 ON message_attributes.message_attribute_id = borrower_message_preferences.message_attribute_id
77 LEFT JOIN message_transports
78 ON message_transports.message_attribute_id = message_attributes.message_attribute_id
79 AND message_transports.message_transport_type = borrower_message_transport_preferences.message_transport_type
80 WHERE message_attributes.message_name = ?
83 my @bind_params = ( $params->{'message_name'} );
84 if ( exists $params->{'borrowernumber'} ) {
85 $sql .= " AND borrower_message_preferences.borrowernumber = ? ";
86 push @bind_params, $params->{borrowernumber};
88 $sql .= " AND borrower_message_preferences.categorycode = ? ";
89 push @bind_params, $params->{categorycode};
92 my $sth = C4::Context->dbh->prepare($sql);
93 $sth->execute(@bind_params);
95 my %transports; # helps build a list of unique message_transport_types
96 ROW: while ( my $row = $sth->fetchrow_hashref() ) {
97 next ROW unless $row->{'message_attribute_id'};
98 $return->{'days_in_advance'} = $row->{'days_in_advance'} if defined $row->{'days_in_advance'};
99 $return->{'wants_digest'} = $row->{'wants_digest'} if defined $row->{'wants_digest'};
100 $return->{'letter_code'} = $row->{'letter_code'};
101 next unless defined $row->{'message_transport_type'};
102 $return->{'transports'}->{ $row->{'message_transport_type'} } = $row->{'letter_code'};
107 =head2 SetMessagingPreference
109 This method defines how a user (or a default for a patron category) wants to get a certain
110 message delivered. The list of valid message types can be delivered can be found in the
111 C<message_attributes> table, and the list of valid message transports can be
112 found in the C<message_transport_types> table.
114 C4::Members::Messaging::SetMessagingPreference( { borrowernumber => $borrower->{'borrowernumber'}
115 message_attribute_id => $message_attribute_id,
116 message_transport_types => [ qw( email sms ) ],
118 wants_digest => 1 } )
120 returns nothing useful.
124 sub SetMessagingPreference {
127 unless (exists $params->{borrowernumber} xor exists $params->{categorycode}) { # yes, xor
128 warn "SetMessagingPreference called without exactly one of borrowernumber or categorycode";
131 foreach my $required ( qw( message_attribute_id message_transport_types ) ) {
132 if ( ! exists $params->{ $required } ) {
133 warn "SetMessagingPreference called without required parameter: $required";
137 $params->{'days_in_advance'} = undef unless exists ( $params->{'days_in_advance'} );
138 $params->{'wants_digest'} = 0 unless exists ( $params->{'wants_digest'} );
140 my $dbh = C4::Context->dbh();
142 my $delete_sql = <<'END_SQL';
143 DELETE FROM borrower_message_preferences
144 WHERE message_attribute_id = ?
146 my @bind_params = ( $params->{'message_attribute_id'} );
147 if ( exists $params->{'borrowernumber'} ) {
148 $delete_sql .= " AND borrowernumber = ? ";
149 push @bind_params, $params->{borrowernumber};
151 $delete_sql .= " AND categorycode = ? ";
152 push @bind_params, $params->{categorycode};
154 my $sth = $dbh->prepare( $delete_sql );
155 my $deleted = $sth->execute( @bind_params );
157 if ( $params->{'message_transport_types'} ) {
158 my $insert_bmp = <<'END_SQL';
159 INSERT INTO borrower_message_preferences
160 (borrower_message_preference_id, borrowernumber, categorycode, message_attribute_id, days_in_advance, wants_digest)
162 (NULL, ?, ?, ?, ?, ?)
165 $sth = C4::Context->dbh()->prepare($insert_bmp);
166 # set up so that we can easily construct the insert SQL
167 $params->{'borrowernumber'} = undef unless exists ( $params->{'borrowernumber'} );
168 $params->{'categorycode'} = undef unless exists ( $params->{'categorycode'} );
169 my $success = $sth->execute( $params->{'borrowernumber'},
170 $params->{'categorycode'},
171 $params->{'message_attribute_id'},
172 $params->{'days_in_advance'},
173 $params->{'wants_digest'} );
174 # my $borrower_message_preference_id = $dbh->last_insert_id();
175 my $borrower_message_preference_id = $dbh->{'mysql_insertid'};
177 my $insert_bmtp = <<'END_SQL';
178 INSERT INTO borrower_message_transport_preferences
179 (borrower_message_preference_id, message_transport_type)
183 $sth = C4::Context->dbh()->prepare($insert_bmtp);
184 foreach my $transport ( @{$params->{'message_transport_types'}}) {
185 my $success = $sth->execute( $borrower_message_preference_id, $transport );
191 =head2 GetMessagingOptions
193 my $messaging_options = C4::Members::Messaging::GetMessagingOptions()
195 returns a hashref of messaging options available.
199 sub GetMessagingOptions {
201 my $sql = <<'END_SQL';
202 select message_attributes.message_attribute_id, takes_days, message_name, message_transport_type, is_digest
203 FROM message_attributes
204 LEFT JOIN message_transports
205 ON message_attributes.message_attribute_id = message_transports.message_attribute_id
208 my $sth = C4::Context->dbh->prepare($sql);
211 while ( my $row = $sth->fetchrow_hashref() ) {
212 $choices->{ $row->{'message_name'} }->{'message_attribute_id'} = $row->{'message_attribute_id'};
213 $choices->{ $row->{'message_name'} }->{'message_name'} = $row->{'message_name'};
214 $choices->{ $row->{'message_name'} }->{'takes_days'} = $row->{'takes_days'};
215 $choices->{ $row->{'message_name'} }->{'has_digest'} = 1 if $row->{'is_digest'};
216 $choices->{ $row->{'message_name'} }->{'transport_' . $row->{'message_transport_type'}} = ' ';
219 my @return = values %$choices;
221 @return = sort { $a->{message_attribute_id} <=> $b->{message_attribute_id} } @return;
223 # warn( Data::Dumper->Dump( [ \@return ], [ 'return' ] ) );
227 =head2 SetMessagingPreferencesFromDefaults
229 C4::Members::Messaging::SetMessagingPreferencesFromDefaults( { borrowernumber => $borrower->{'borrowernumber'}
230 categorycode => 'CPL' } );
232 Given a borrowernumber and a patron category code (from the C<borrowernumber> and C<categorycode> keys
233 in the parameter hashref), replace all of the patron's current messaging preferences with
234 whatever defaults are defined for the patron category.
238 sub SetMessagingPreferencesFromDefaults {
241 foreach my $required ( qw( borrowernumber categorycode ) ) {
242 unless ( exists $params->{ $required } ) {
243 die "SetMessagingPreferencesFromDefaults called without required parameter: $required";
247 my $messaging_options = GetMessagingOptions();
248 OPTION: foreach my $option ( @$messaging_options ) {
249 my $default_pref = GetMessagingPreferences( { categorycode => $params->{categorycode},
250 message_name => $option->{'message_name'} } );
251 # FIXME - except for setting the borrowernumber, it really ought to be possible
252 # to have the output of GetMessagingPreferences be able to be the input
253 # to SetMessagingPreference
254 my @message_transport_types = keys %{ $default_pref->{transports} };
255 $default_pref->{message_attribute_id} = $option->{'message_attribute_id'};
256 $default_pref->{message_transport_types} = \@message_transport_types;
257 $default_pref->{borrowernumber} = $params->{borrowernumber};
258 SetMessagingPreference( $default_pref );
266 The actual messages which will be sent via a cron job running
267 F<misc/cronjobs/process_message_queue.pl>.
269 =head2 message_attributes
271 What kinds of messages can be sent?
273 =head2 message_transport_types
275 What transports can messages be sent vith? (email, sms, etc.)
277 =head2 message_transports
279 How are message_attributes and message_transport_types correlated?
281 =head2 borrower_message_preferences
283 What messages do the borrowers want to receive?
285 =head2 borrower_message_transport_preferences
287 What transport should a message be sent with?
291 =head2 Adding a New Kind of Message to the System
297 Add a new template to the `letter` table.
301 Insert a row into the `message_attributes` table.
305 Insert rows into `message_transports` for each message_transport_type.
315 Koha Development Team <http://koha-community.org/>
317 Andrew Moore <andrew.moore@liblime.com>