Repository navigation
Using Bulkrax without Hyrax
Bulkrax can run in a Rails application that does not use Hyrax, as long as the application supplies the pieces Hyrax would otherwise provide. This page lists those pieces.
Bulkrax releases after 8.3 have not been fully tested without Hyrax, so bugs may remain. The Bulkrax test suite covers CSV imports and exports of works without Hyrax, through a stand-in object factory, on Rails 7.0 and 8.1 (spec/without_hyrax). It does not cover other parsers, collections, file sets, or a real repository such as Fedora and Solr. If you run Bulkrax without Hyrax, please report what breaks.
Bulkrax creates, finds and updates records through an object factory, set with config.object_factory. Anything that depends on a particular repository belongs in the factory, so the rest of Bulkrax does not need to know about it.
You can build the factory in one of two ways:
-
Subclass
Bulkrax::ObjectFactory, which is written for ActiveFedora. Your application then needs ActiveFedora, which brings in ActiveTriples, and a Solr index for exports.Bulkrax::ObjectFactorycreates and updates works through Hyrax's actor stack, so your subclass must override eithercreateandupdate, orcreate_workandupdate_work. Override any other methods whose ActiveFedora behavior does not suit your models. -
Implement
Bulkrax::ObjectFactoryInterfaceyourself, for an application without ActiveFedora. Bulkrax calls at least these class methods:-
find(id), which raisesBulkrax::ObjectFactoryInterface::ObjectNotFoundErrorwhen nothing matches -
save!(resource:, user:),update_index(resources:)andpublish(event:, **) -
add_child_to_parent_work(parent:, child:), which returns the parent -
field_supported?(field:, model:)andfield_multi_value?(field:, model:) - for exports:
query(query, **options), which returns Solr-style documents with an'id';solr_name(field_name);model_name(resource:);export_values(values)andexport_value(value)
It also needs the instance methods
run!,create,updateandfind, which import calls for each row. -
Bulkrax calls Ability.new(user) and expects your application to define Ability:
- Include
Bulkrax::AbilityBehavior, and overridecan_import_works?,can_export_works?,can_admin_importers?andcan_admin_exporters?to say who may import and export. Exports callcan_admin_exporters?. -
authorize!(:edit, record)must allow the importing user to edit the records it relates to each other.
class Ability
include Hydra::Ability # or your own CanCan ability
include Bulkrax::AbilityBehavior
self.ability_logic += [:bulkrax_default_abilities]
def can_import_works?
current_user.admin?
end
def can_export_works?
current_user.admin?
end
endImporters and exporters belong to a user, so your application needs a User model. Without Hyrax there is no fallback batch user: an importer or exporter without a user fails.
Set your work models and the default one:
Bulkrax.setup do |config|
config.object_factory = MyObjectFactory
config.curation_concerns = [MyWork]
config.default_work_type = 'MyWork'
config.file_model_class = MyFile
# config.collection_model_class = MyCollection
endEach work model needs to:
- answer
propertieswith a hash of field names, each saying whether it holds several values ({ 'title' => { 'multiple' => false } }) - define its field accessors when the class loads, since Bulkrax checks
method_defined?to see which fields a model supports - accept
visibility, which Bulkrax sends with every row - answer
work?andcollection?, which relating records checks
With a factory that subclasses Bulkrax::ObjectFactory, models also need ActiveFedora's ordered_members (for relating child works to a parent) and has_model (for exports).
File model. Set file_model_class. Without Hyrax it defaults to Ruby's File, and exports fail when they look for file sets.
Collection model. collection_model_class is optional. Without one, rows can still relate works to each other, and exports skip collections.
Entry classes read default_work_type when they first load. If your application configures Bulkrax after that, for example inside Rails.application.config.to_prepare, rows without a model column get no work type. Set it on the entry class as well:
Bulkrax::CsvEntry.default_work_type = 'MyWork'Give each parser a field mapping, with one field marked as the source identifier:
config.field_mappings = {
'Bulkrax::CsvParser' => {
'source_identifier' => { from: ['source_identifier'], source_identifier: true },
'title' => { from: ['title'] },
'creator' => { from: ['creator'], split: true },
'parents' => { from: ['parents'], related_parents_field_mapping: true, split: true }
}
}The importer form copies the mapping for the chosen parser onto each new importer.
Imports and exports run as Active Job jobs. Relating records runs a few minutes after the rows are imported, so your queue adapter must run scheduled jobs.
Mount the engine in config/routes.rb:
mount Bulkrax::Engine, at: '/'Then run bin/rails db:migrate. The engine adds its migrations to your application's migration path.