1 package Koha::BackgroundJob;
3 # This file is part of Koha.
5 # Koha is free software; you can redistribute it and/or modify it
6 # under the terms of the GNU General Public License as published by
7 # the Free Software Foundation; either version 3 of the License, or
8 # (at your option) any later version.
10 # Koha is distributed in the hope that it will be useful, but
11 # WITHOUT ANY WARRANTY; without even the implied warranty of
12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 # GNU General Public License for more details.
15 # You should have received a copy of the GNU General Public License
16 # along with Koha; if not, see <http://www.gnu.org/licenses>.
19 use JSON qw( decode_json encode_json );
20 use Encode qw( encode_utf8 );
23 use Try::Tiny qw( catch try );
26 use Koha::DateUtils qw( dt_from_string );
29 use Koha::Exceptions::BackgroundJob;
31 use base qw( Koha::Object );
35 Koha::BackgroundJob - Koha BackgroundJob Object class
37 This is a base class for BackgroundJob, some methods must be subclassed.
42 my $job_id = Koha::BackgroundJob->enqueue(
44 job_type => $job_type,
45 job_size => $job_size,
51 Koha::BackgrounJobs->find($job_id)->process;
52 See also C<misc/background_jobs_worker.pl> for a full example
60 Connect to the message broker using default guest/guest credential
66 my $hostname = 'localhost';
68 my $config = C4::Context->config('message_broker');
74 $hostname = $config->{hostname} if $config->{hostname};
75 $port = $config->{port} if $config->{port};
76 $credentials->{login} = $config->{username} if $config->{username};
77 $credentials->{passcode} = $config->{password} if $config->{password};
78 $credentials->{host} = $config->{vhost} if $config->{vhost};
80 my $stomp = Net::Stomp->new( { hostname => $hostname, port => $port } );
81 $stomp->connect( $credentials );
87 Enqueue a new job. It will insert a new row in the DB table and notify the broker that a new job has been enqueued.
89 C<job_size> is the size of the job
90 C<job_args> is the arguments of the job. It's a structure that will be JSON encoded.
92 Return the job_id of the newly created job.
97 my ( $self, $params ) = @_;
99 my $job_type = $self->job_type;
100 my $job_size = $params->{job_size};
101 my $job_args = $params->{job_args};
102 my $job_queue = $params->{job_queue} // 'default';
104 my $borrowernumber = (C4::Context->userenv) ? C4::Context->userenv->{number} : undef;
105 my $json_args = encode_json $job_args;
114 enqueued_on => dt_from_string,
115 borrowernumber => $borrowernumber,
119 $job_args->{job_id} = $self->id;
123 $conn = $self->connect;
125 warn "Cannot connect to broker " . $_;
129 $json_args = encode_json $job_args;
131 # This namespace is wrong, it must be a vhost instead.
132 # But to do so it needs to be created on the server => much more work when a new Koha instance is created.
133 # Also, here we just want the Koha instance's name, but it's not in the config...
134 # Picking a random id (memcached_namespace) from the config
135 my $namespace = C4::Context->config('memcached_namespace');
136 $conn->send_with_receipt( { destination => sprintf("/queue/%s-%s", $namespace, $job_queue), body => $json_args } )
137 or Koha::Exceptions::Exception->throw('Job has not been enqueued');
139 $self->status('failed')->store;
140 if ( ref($_) eq 'Koha::Exceptions::Exception' ) {
143 warn sprintf "The job has not been sent to the message broker: (%s)", $_;
157 my ( $self, $args ) = @_;
159 return {} if ref($self) ne 'Koha::BackgroundJob';
161 my $derived_class = $self->_derived_class;
165 return $derived_class->process( $args );
172 Marks the job as started.
179 Koha::Exceptions::BackgroundJob::InconsistentStatus->throw(
180 current_status => $self->status,
181 expected_status => 'new'
182 ) unless $self->status eq 'new';
186 started_on => \'NOW()',
197 Makes the job record a step has taken place.
204 Koha::Exceptions::BackgroundJob::InconsistentStatus->throw(
205 current_status => $self->status,
206 expected_status => 'started'
207 ) unless $self->status eq 'started';
209 # reached the end of the tasks already
210 Koha::Exceptions::BackgroundJob::StepOutOfBounds->throw()
211 unless $self->progress < $self->size;
213 return $self->progress( $self->progress + 1 )->store;
220 Makes the job record as finished. If the job status is I<cancelled>, it is kept.
225 my ( $self, $data ) = @_;
227 $self->status('finished') unless $self->status eq 'cancelled';
231 ended_on => \'NOW()',
232 data => encode_json($data),
239 my $job_data = $self->decoded_data;
241 Returns the decoded JSON contents from $self->data.
248 return decode_json($self->data);
251 =head3 set_encoded_data
253 $self->set_encoded_data( $data );
255 Serializes I<$data> as a JSON string and sets the I<data> attribute with it.
259 sub set_encoded_data {
260 my ( $self, $data ) = @_;
262 return $self->data( encode_json($data) );
267 Return the job type of the job. Must be a string.
271 sub job_type { croak "This method must be subclassed" }
275 Messages let during the processing of the job.
283 my $data_dump = decode_json encode_utf8 $self->data;
284 if ( exists $data_dump->{messages} ) {
285 @messages = @{ $data_dump->{messages} };
300 my $data_dump = decode_json encode_utf8 $self->data;
301 return $data_dump->{report} || {};
304 =head3 additional_report
306 Build additional variables for the job detail view.
310 sub additional_report {
313 return {} if ref($self) ne 'Koha::BackgroundJob';
315 my $derived_class = $self->_derived_class;
317 return $derived_class->additional_report;
328 $self->status('cancelled')->store;
331 =head2 Internal methods
333 =head3 _derived_class
339 my $job_type = $self->type;
341 my $class = $self->type_to_class_mapping->{$job_type};
343 Koha::Exception->throw($job_type . ' is not a valid job_type')
346 eval "require $class";
347 return $class->_new_from_dbic( $self->_result );
350 =head3 type_to_class_mapping
352 my $mapping = Koha::BackgrounJob->new->type_to_class_mapping;
354 Returns the available types to class mappings.
358 sub type_to_class_mapping {
361 my $plugins_mapping = $self->plugin_types_to_classes;
363 return ($plugins_mapping)
364 ? { %{ $self->core_types_to_classes }, %$plugins_mapping }
365 : $self->core_types_to_classes;
368 =head3 core_types_to_classes
370 my $mappings = Koha::BackgrounJob->new->core_types_to_classes
372 Returns the core background jobs types to class mappings.
376 sub core_types_to_classes {
378 batch_authority_record_deletion => 'Koha::BackgroundJob::BatchDeleteAuthority',
379 batch_authority_record_modification => 'Koha::BackgroundJob::BatchUpdateAuthority',
380 batch_biblio_record_deletion => 'Koha::BackgroundJob::BatchDeleteBiblio',
381 batch_biblio_record_modification => 'Koha::BackgroundJob::BatchUpdateBiblio',
382 batch_item_record_deletion => 'Koha::BackgroundJob::BatchDeleteItem',
383 batch_item_record_modification => 'Koha::BackgroundJob::BatchUpdateItem',
384 batch_hold_cancel => 'Koha::BackgroundJob::BatchCancelHold',
385 update_elastic_index => 'Koha::BackgroundJob::UpdateElasticIndex',
386 update_holds_queue_for_biblios => 'Koha::BackgroundJob::BatchUpdateBiblioHoldsQueue',
390 =head3 plugin_types_to_classes
392 my $mappings = Koha::BackgroundJob->new->plugin_types_to_classes
394 Returns the plugin-defined background jobs types to class mappings.
398 sub plugin_types_to_classes {
401 unless ( exists $self->{_plugin_mapping} ) {
402 my @plugins = Koha::Plugins->new()->GetPlugins( { method => 'background_tasks', } );
404 foreach my $plugin (@plugins) {
406 my $tasks = $plugin->background_tasks;
407 my $metadata = $plugin->get_metadata;
409 unless ( $metadata->{namespace} ) {
410 Koha::Logger->get->warn(
411 q{A plugin includes the 'background_tasks' method, }
412 . q{but doesn't provide the required 'namespace' }
413 . qq{method ($plugin->{class})} );
417 my $namespace = $metadata->{namespace};
419 foreach my $type ( keys %{$tasks} ) {
420 my $class = $tasks->{$type};
422 # skip if conditions not met
423 next unless $type and $class;
425 my $key = "plugin_$namespace" . "_$type";
427 $self->{_plugin_mapping}->{$key} = $tasks->{$type};
432 return $self->{_plugin_mapping};
440 return 'BackgroundJob';