Skip to content

Using Bulkrax without Hyrax

LaRita Robinson edited this page Nov 19, 2026 · 2 revisions

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.

Object factory

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::ObjectFactory creates and updates works through Hyrax's actor stack, so your subclass must override either create and update, or create_work and update_work. Override any other methods whose ActiveFedora behavior does not suit your models.

  • Implement Bulkrax::ObjectFactoryInterface yourself, for an application without ActiveFedora. Bulkrax calls at least these class methods:

    • find(id), which raises Bulkrax::ObjectFactoryInterface::ObjectNotFoundError when nothing matches
    • save!(resource:, user:), update_index(resources:) and publish(event:, **)
    • add_child_to_parent_work(parent:, child:), which returns the parent
    • field_supported?(field:, model:) and field_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) and export_value(value)

    It also needs the instance methods run!, create, update and find, which import calls for each row.

Ability

Bulkrax calls Ability.new(user) and expects your application to define Ability:

  • Include Bulkrax::AbilityBehavior, and override can_import_works?, can_export_works?, can_admin_importers? and can_admin_exporters? to say who may import and export. Exports call can_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
end

User

Importers 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.

Models

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
end

Each work model needs to:

  • answer properties with 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? and collection?, 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.

Default work type

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'

Field mappings

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.

Background jobs

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.

Engine

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.

Clone this wiki locally