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>.
23 use Try::Tiny qw( catch try );
26 use Koha::DateUtils qw( dt_from_string );
28 use Koha::Exceptions::BackgroundJob;
30 use base qw( Koha::Object );
34 Koha::BackgroundJob - Koha BackgroundJob Object class
36 This is a base class for BackgroundJob, some methods must be subclassed.
41 my $job_id = Koha::BackgroundJob->enqueue(
43 job_type => $job_type,
44 job_size => $job_size,
50 Koha::BackgroundJobs->find($job_id)->process;
51 See also C<misc/background_jobs_worker.pl> for a full example
59 Connect to the message broker using default guest/guest credential
65 my $hostname = 'localhost';
67 my $config = C4::Context->config('message_broker');
73 $hostname = $config->{hostname} if $config->{hostname};
74 $port = $config->{port} if $config->{port};
75 $credentials->{login} = $config->{username} if $config->{username};
76 $credentials->{passcode} = $config->{password} if $config->{password};
77 $credentials->{host} = $config->{vhost} if $config->{vhost};
79 my $stomp = Net::Stomp->new( { hostname => $hostname, port => $port } );
80 $stomp->connect( $credentials );
86 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.
88 C<job_size> is the size of the job
89 C<job_args> is the arguments of the job. It's a structure that will be JSON encoded.
91 Return the job_id of the newly created job.
96 my ( $self, $params ) = @_;
98 my $job_type = $self->job_type;
99 my $job_size = $params->{job_size};
100 my $job_args = $params->{job_args};
101 my $job_context = $params->{job_context} // C4::Context->userenv;
102 my $job_queue = $params->{job_queue} // 'default';
103 my $json = $self->json;
105 my $borrowernumber = (C4::Context->userenv) ? C4::Context->userenv->{number} : undef;
106 $job_context->{interface} = C4::Context->interface;
107 my $json_context = $json->encode($job_context);
108 my $json_args = $json->encode($job_args);
117 context => $json_context,
118 enqueued_on => dt_from_string,
119 borrowernumber => $borrowernumber,
123 $job_args->{job_id} = $self->id;
127 $conn = $self->connect;
129 warn "Cannot connect to broker " . $_;
131 return $self->id unless $conn;
133 $json_args = $json->encode($job_args);
135 # This namespace is wrong, it must be a vhost instead.
136 # But to do so it needs to be created on the server => much more work when a new Koha instance is created.
137 # Also, here we just want the Koha instance's name, but it's not in the config...
138 # Picking a random id (memcached_namespace) from the config
139 my $namespace = C4::Context->config('memcached_namespace');
140 my $encoded_args = Encode::encode_utf8( $json_args ); # FIXME We should better leave this to Net::Stomp?
141 my $destination = sprintf( "/queue/%s-%s", $namespace, $job_queue );
142 $conn->send_with_receipt( { destination => $destination, body => $encoded_args, persistent => 'true' } )
143 or Koha::Exceptions::BackgroundJob->throw('Job has not been enqueued');
145 $self->status('failed')->store;
146 if ( ref($_) eq 'Koha::Exceptions::BackgroundJob' ) {
149 warn sprintf "The job has not been sent to the message broker: (%s)", $_;
163 my ( $self, $args ) = @_;
165 return {} if ref($self) ne 'Koha::BackgroundJob';
167 my $derived_class = $self->_derived_class;
171 if ( $self->context ) {
172 my $context = $self->json->decode($self->context);
173 C4::Context->_new_userenv(-1);
174 C4::Context->interface( $context->{interface} );
175 C4::Context->set_userenv(
176 $context->{number}, $context->{id},
177 $context->{cardnumber}, $context->{firstname},
178 $context->{surname}, $context->{branch},
179 $context->{branchname}, $context->{flags},
180 $context->{emailaddress}, undef,
181 $context->{desk_id}, $context->{desk_name},
182 $context->{register_id}, $context->{register_name}
186 Koha::Logger->get->warn("A background job didn't have context defined (" . $self->id . ")");
189 return $derived_class->process( $args );
196 Marks the job as started.
203 Koha::Exceptions::BackgroundJob::InconsistentStatus->throw(
204 current_status => $self->status,
205 expected_status => 'new'
206 ) unless $self->status eq 'new';
210 started_on => \'NOW()',
221 Makes the job record a step has taken place.
228 Koha::Exceptions::BackgroundJob::InconsistentStatus->throw(
229 current_status => $self->status,
230 expected_status => 'started'
231 ) unless $self->status eq 'started';
233 # reached the end of the tasks already
234 Koha::Exceptions::BackgroundJob::StepOutOfBounds->throw()
235 unless $self->progress < $self->size;
237 return $self->progress( $self->progress + 1 )->store;
244 Makes the job record as finished. If the job status is I<cancelled>, it is kept.
249 my ( $self, $data ) = @_;
251 $self->status('finished') unless $self->status eq 'cancelled' or $self->status eq 'failed';
255 ended_on => \'NOW()',
256 data => $self->json->encode($data),
263 my $JSON_object = $self->json;
265 Returns a JSON object with utf8 disabled. Encoding to UTF-8 should be
272 $self->{_json} //= JSON->new->utf8(0); # TODO Should we allow_nonref ?
273 return $self->{_json};
278 my $job_data = $self->decoded_data;
280 Returns the decoded JSON contents from $self->data.
287 return $self->data ? $self->json->decode( $self->data ) : undef;
290 =head3 set_encoded_data
292 $self->set_encoded_data( $data );
294 Serializes I<$data> as a JSON string and sets the I<data> attribute with it.
298 sub set_encoded_data {
299 my ( $self, $data ) = @_;
301 return $self->data( $data ? $self->json->encode($data) : undef );
306 Return the job type of the job. Must be a string.
310 sub job_type { croak "This method must be subclassed" }
314 Messages let during the processing of the job.
322 my $data_dump = $self->json->decode($self->data);
323 if ( exists $data_dump->{messages} ) {
324 @messages = @{ $data_dump->{messages} };
339 my $data_dump = $self->json->decode($self->data);
340 return $data_dump->{report} || {};
343 =head3 additional_report
345 Build additional variables for the job detail view.
349 sub additional_report {
352 return {} if ref($self) ne 'Koha::BackgroundJob';
354 my $derived_class = $self->_derived_class;
356 return $derived_class->additional_report;
367 $self->status('cancelled')->store;
370 =head2 Internal methods
372 =head3 _derived_class
378 my $job_type = $self->type;
380 my $class = $self->type_to_class_mapping->{$job_type};
382 Koha::Exception->throw($job_type . ' is not a valid job_type')
385 eval "require $class";
386 return $class->_new_from_dbic( $self->_result );
389 =head3 type_to_class_mapping
391 my $mapping = Koha::BackgroundJob->new->type_to_class_mapping;
393 Returns the available types to class mappings.
397 sub type_to_class_mapping {
400 my $plugins_mapping = ( C4::Context->config("enable_plugins") ) ? $self->plugin_types_to_classes : {};
402 return ($plugins_mapping)
403 ? { %{ $self->core_types_to_classes }, %$plugins_mapping }
404 : $self->core_types_to_classes;
407 =head3 core_types_to_classes
409 my $mappings = Koha::BackgroundJob->new->core_types_to_classes
411 Returns the core background jobs types to class mappings.
415 sub core_types_to_classes {
417 batch_authority_record_deletion => 'Koha::BackgroundJob::BatchDeleteAuthority',
418 batch_authority_record_modification => 'Koha::BackgroundJob::BatchUpdateAuthority',
419 batch_biblio_record_deletion => 'Koha::BackgroundJob::BatchDeleteBiblio',
420 batch_biblio_record_modification => 'Koha::BackgroundJob::BatchUpdateBiblio',
421 batch_item_record_deletion => 'Koha::BackgroundJob::BatchDeleteItem',
422 batch_item_record_modification => 'Koha::BackgroundJob::BatchUpdateItem',
423 erm_sushi_harvester => 'Koha::BackgroundJob::ErmSushiHarvester',
424 batch_hold_cancel => 'Koha::BackgroundJob::BatchCancelHold',
425 create_eholdings_from_biblios => 'Koha::BackgroundJob::CreateEHoldingsFromBiblios',
426 update_elastic_index => 'Koha::BackgroundJob::UpdateElasticIndex',
427 update_holds_queue_for_biblios => 'Koha::BackgroundJob::BatchUpdateBiblioHoldsQueue',
428 stage_marc_for_import => 'Koha::BackgroundJob::StageMARCForImport',
429 marc_import_commit_batch => 'Koha::BackgroundJob::MARCImportCommitBatch',
430 marc_import_revert_batch => 'Koha::BackgroundJob::MARCImportRevertBatch',
431 pseudonymize_statistic => 'Koha::BackgroundJob::PseudonymizeStatistic',
432 import_from_kbart_file => 'Koha::BackgroundJob::ImportKBARTFile',
436 =head3 plugin_types_to_classes
438 my $mappings = Koha::BackgroundJob->new->plugin_types_to_classes
440 Returns the plugin-defined background jobs types to class mappings.
444 sub plugin_types_to_classes {
447 unless ( exists $self->{_plugin_mapping} ) {
448 require Koha::Plugins;
449 my @plugins = Koha::Plugins->new()->GetPlugins( { method => 'background_tasks', } );
451 foreach my $plugin (@plugins) {
453 my $tasks = $plugin->background_tasks;
454 my $metadata = $plugin->get_metadata;
456 unless ( $metadata->{namespace} ) {
457 Koha::Logger->get->warn(
458 q{A plugin includes the 'background_tasks' method, }
459 . q{but doesn't provide the required 'namespace' }
460 . qq{method ($plugin->{class})} );
464 my $namespace = $metadata->{namespace};
466 foreach my $type ( keys %{$tasks} ) {
467 my $class = $tasks->{$type};
469 # skip if conditions not met
470 next unless $type and $class;
472 my $key = "plugin_$namespace" . "_$type";
474 $self->{_plugin_mapping}->{$key} = $tasks->{$type};
479 return $self->{_plugin_mapping};
484 my $json = $job->to_api;
486 Overloaded method that returns a JSON representation of the Koha::BackgroundJob object,
487 suitable for API output.
492 my ( $self, $params ) = @_;
494 my $json = $self->SUPER::to_api( $params );
496 $json->{context} = $self->json->decode($self->context)
497 if defined $self->context;
498 $json->{data} = $self->decoded_data;
503 =head3 to_api_mapping
505 This method returns the mapping for representing a Koha::BackgroundJob object
513 borrowernumber => 'patron_id',
514 ended_on => 'ended_date',
515 enqueued_on => 'enqueued_date',
516 started_on => 'started_date',
525 return 'BackgroundJob';