Skip to content

HykuAddons: Migrating Work Types to Schemas

Jump to bottom
Paul Danelli edited this page Mar 3, 2022 · 9 revisions

Below are the steps to migrate an existing work to the Schema YAML.

For an example PR illustrating how to migrate a work type from the legacy configuration to the schema YAML, See here

Step 1

docker-compose exec web rails app:hyku_addons:model:generate_schema[anschutz_work]

Step 2

Manually compare the generated schema created in config/metadata/anschutz_work.yaml to the form which is shown in your locally development environment.

Dashboard YAML

The schema generator will try its best to work out the correct fields and their settings (multiple, primary etc), however for subfields like Creator/Contributor/Editor/Funder etc, it is not possible, so pay close attention to the JSON fields.

There maybe differences in how the select fields are generated. You should be able to find most fields by consulting the existing schema YAML files.

Views / partials

Form field partials are requested from a prioritised list of locations inside of Hyrax, which is inherited from the Hrdra Editor Gem. The legacy method of introducing changes to the form fields was to include a series of partials which overrode the original. As a consequence, you will need to check any partials which relate to the work type you are migrating, in order to see if there are any differences from the defaults.

For instance, in the AnschutzWork migration, the "required" attribute was added to the year select of the date_published field, which wouldn't be immediately obvious.

Examples

Examples of common and more complicated field definitions can also be found here: https://github.com/ubiquitypress/hyku_addons/wiki/HykuAddons:-Creating-new-work-types#schema-examples

Step 3

Convert the existing Work/Form/Indexer/Presenter classes to use the correct Schema Concerns, as illustrated here: https://github.com/ubiquitypress/hyku_addons/wiki/HykuAddons:-Creating-new-work-types#adding-the-required-concerns

You will have to replace the HykuAddons concerns with the new HykuAddons::Schema versions. If you are unsure, consult one of the already converted modules, UvaWork or UbiquityTemplateWork.

For the work model, it should look similar to this - app/models/anschutz_work.rb:

class AnschutzWork < ActiveFedora::Base
  include Hyrax::WorkBehavior
  include Hyrax::DOI::DataCiteDOIBehavior

  include HykuAddons::Schema::WorkBase
  include Hyrax::Schema(:anschutz_work)
  include Hyrax::BasicMetadata

  self.indexer = AnschutzWorkIndexer
  
  validates :title, presence: { message: "Your work must have a title." }
end

The form - app/form/hyrax/anschutz_work_form.rb

module Hyrax
  class AnschutzWorkForm < Hyrax::Forms::WorkForm
    include Hyrax::DOI::DataCiteDOIFormBehavior

    include ::HykuAddons::Schema::WorkForm
    include Hyrax::FormFields(:anschutz_work)

    self.model_class = ::AnschutzWork
  end
end

The presenter - app/hyrax/presenters/anschutz_work_presenter.rb:

module Hyrax
  class AnschutzWorkPresenter < Hyrax::WorkShowPresenter
    # The order of these includes is important
    include ::HykuAddons::Schema::Presenter(:anschutz_work)
    include ::HykuAddons::WorkPresenterBehavior
    include ::HykuAddons::PresenterDelegatable
  end
end

The indexer - app/indexers/anschutz_work_indexer.rb

class AnschutzWorkIndexer < Hyrax::WorkIndexer
  include Hyrax::Indexer(:anschutz_work)
  include Hyrax::IndexesBasicMetadata
  include Hyrax::IndexesLinkedMetadata
end

Please note, since the doi field was added to the form fields, and removed from its own tab, it should be added to the schema. This means that the Hyrax::DOI concerns for the Work and Form are not required.

# Neither of these two concerns should be added
include Hyrax::DOI::DOIBehavior
include Hyrax::DOI::DOIFormBehavior

Step 4

Change the "locale" in the properior (super-admin) account settings to ensure you are seeing exactly what the production tenant is supposed to look like.

Reload your development environment and make sure everything is loading correctly.

Step 5

Previously testing the forms was not a priority, partly because testing an entire form is incredibly slow and complicated. Substantial work has been completed to make automating the process as simple as possible.

Inside of spec/support/fill_in_fields.rb you will find an array of form field helper methods to allow you to add a single line and add input to a properly structured schema field. For example:

fill_in_cloneable(:creator, creator)
fill_in_text_field(:advisor, advisor)
fill_in_multiple_text_fields(:publisher, publisher)
fill_in_select(:repository_space, repository_space_options["label"])

Other helper methods which maybe of use if you are debugging the specs are:

# Take a ScreenShot of the page
ss

# Scroll up (with plus numbers) and down (with negative numbers)
scroll(1000)
scroll(-1000)

Inside of spec/support/work_form_helpers.rb you will find a series of more generic helpers that can add files, check the agreement and submit the form.

If you check inside of spec/features/ubiquity_template_work_form_spec.rb you will find a nearly (depending on if it has been maintained) complete collection of fields. You can therefore duplicate this file, update the let(:work_type) { "ubiquity_template_work" } variable to your work type name and remove any unwanted fields.

This is an example of filling out a "multiple text" field - leaving out the setup for brevity:

# Set the values
let(:alt_title) { ["Alt Title 1", "Alt Title 2"] }

# Fill in the field
fill_in_multiple_text_fields(:alt_title, alt_title)

# The expectations
alt_title.each { |alt| expect(page).to have_content(alt) }
expect(work.alt_title).to eq(alt_title)

Other examples you can use are spec/features/uva_work_form_spec.rb and spec/features/anschutz_work_form_spec.rb.

Step 6

It's important to manually compare the API response for the demo site and the API response returned from your local machine.

To access the API on your local machine, see this wiki article.

You can then compare the JSON which is returned to the browser from each source, line by line and check for any differences.

image

Please note, the images above are using a chrome extension to format the JSON for easier reading.

Issues you may run into

Finding the fields Solr Name

If you wish to check the name of the field inside of Solr, you can use:

# ::SolrDocument.solr_name("your_field")

::SolrDocument.solr_name("title")
=> "title_tesim"

Hyrax fields

The license and rights_statement fields need to be set as multiple, or they will be cast as multiple in the Model Actor.

Controlled Properties

If you receive the following error:

undefined method `controlled_properties' for #YourModel

You have forgotten to include the Hyrax::BasicMetadata concern inside your Work Type model class.

Non-split field test failures

If you see the following error on your work fields it could mean that the field has not been added to the Bulkrax.field_map method which is found inside config/initializers/bulkrax.rb

    1.4) Failure/Error: expect(expectation[:actual]).to eq(expectation[:test]), error_message

            expected place_of_publication to equal ["place_of_publication-0", "place_of_publication-1", "place_of_publication-2"] but got #<ActiveTriples::Relation:0x00005643c816cc88>
            Diff:
            @@ -1 +1 @@
            -["place_of_publication-0", "place_of_publication-1", "place_of_publication-2"]
            +["place_of_publication-0|place_of_publication-1|place_of_publication-2"]

          # ./spec/features/bulkrax_dynamic_import_spec.rb:77:in `block (6 levels) in <top (required)>'
          # ./spec/features/bulkrax_dynamic_import_spec.rb:75:in `each'
          # ./spec/features/bulkrax_dynamic_import_spec.rb:75:in `block (5 levels) in <top (required)>'
          # ./spec/features/bulkrax_dynamic_import_spec.rb:71:in `block (4 levels) in <top (required)>'
Clone this wiki locally