Migrations & Updates

• Inside invenio.cfg, locate from oarepo import config and replace it with import oarepo_config as config
• Inside pyproject.toml, change the dependency from oarepo-app==6.2.0 to oarepo-app==6.3.0
• Run ./run.sh upgrade to bring in new libraries
• Run ./run.sh invenio rdm rebuild-all-indices

1. Update pyproject.toml

Bump the oarepo-app dependency to 6.2.0. If your dependency is a range such as oarepo-app[production,ccmm]>=2.0.1,<3.0.0, replace it with an exact pin.

Before:

dependencies = [
    "oarepo[s3,rdm]>=14.0.0b1,<15.0.0",
    "oarepo-app[production,ccmm]==4.0.0",
]

After:

dependencies = [
    "oarepo[s3,rdm]>=14.0.0b1,<15.0.0",
    "oarepo-app[production,ccmm]==6.2.0",
]

The oarepo[s3,rdm] line needs no change — its range already covers the oarepo version pulled in by the production extra. The production extra now also includes oarepo-related-resources, so that package is installed automatically.

2. Reinstall and reinitialize the database and index

The invenio-rdm-records major bump changed the database schema and the search mappings, so the database and indices need to be brought in line with the new versions. Follow Database and index reinitialization:

• Local development: ./run.sh reset — wipes all data and performs a full reinstall and reinitialization in one step. It includes the reinstall that ./run.sh upgrade does, so no separate upgrade is needed.
• Production: reinstall, then migrate the database and rebuild the index to preserve data:

  ./run.sh upgrade                   # reinstall with the new versions
  ./run.sh invenio alembic upgrade   # run database migrations
  ./run.sh index rebuild             # drop, recreate and reindex OpenSearch
  ./run.sh run                       # so Celery workers process the reindex queue

3. Review behavioral changes and new features

The upgrade introduces several behavioral changes that may affect your repository:

• RDM file service configs now apply. Models using the RDM preset now use RDMFileService and RDMFileServiceConfig (oarepo-rdm 8.1.0) instead of the base FileService. This means RDM file-related configuration — such as RDM_RECORDS_MAX_FILES_COUNT (file count limit) — is now enforced. If your repository previously had no file count limits, review the RDM file config defaults  and adjust if needed.

• PID/DOI field in the deposit form. The “General information” section of the deposit form now includes a PID/DOI field (via RDMPIDsConfigComponent, oarepo-rdm 8.1.0). The field appears when DOI providers are configured. To disable it, either don’t configure DOI providers or override the PIDField overridable component in your model’s deposit form.

• Export sidebar filters by display. The export sidebar now only shows exporters where display=True (oarepo-ui 13.2.3). The Export dataclass defaults display=True, so most exports are unaffected. But exports registered with display=False (e.g., OAI-only exports) are no longer visible in the UI. To show an export, set display=True on the Export instance or AddMetadataExport customization in your model definition.

• ZIP content previewing (invenio-app-rdm 14.0.0rc2). ZIP files can now be browsed and their contents previewed inline. Enabled by default; controlled by PREVIEWABLE_ZIP_PREVIEWER_NATIVE_EXTENSIONS (default ["zip"]). No action needed unless you want to disable it.

• /uploads/new model selection page (oarepo-rdm 8.1.0). The /uploads/new route now shows a model selection page when multiple models exist, or redirects directly when only one model exists. Additive; no action needed.

• RDM-specific behaviour moved out of RecordsUIResource (oarepo-ui 13.0+). RDM-specific behaviour (default files.enabled, pids initialisation, APP_RDM_DEPOSIT_FORM_DEFAULTS, parent-DOI injection for preview, and DOI-required checks) was removed from the base RecordsUIResource in oarepo-ui and moved into separate UI components that ship with oarepo-rdm: FilesEnabledComponent, EmptyRecordPidsComponent, DepositFormDefaultsComponent, InjectParentDoiComponent, DoiRequiredComponent, and RDMPIDsConfigComponent. If your UI resource and config inherit directly from the generic RecordsUIResource / RecordsUIResourceConfig (in oarepo_ui.resources.records), the new-record form will silently lose default files/PIDs/DOI handling — you must switch your base class. Edit ui/<model_name>/__init__.py (for example, ui/datasets/__init__.py).

  For a CCMM-based model — inherit from CCMMRecordsUIResourceConfig and CCMMRecordsUIResource, imported from:

  • from ccmm_invenio.ui.config import CCMMRecordsUIResourceConfig
  • from ccmm_invenio.ui.resource import CCMMRecordsUIResource
  ui/<model_name>/__init__.py

  # Before
  from oarepo_ui.resources.records.config import RecordsUIResourceConfig
  from oarepo_ui.resources.records.resource import RecordsUIResource
   
  class DatasetsUIResourceConfig(RecordsUIResourceConfig):
      ...
   
  class DatasetsUIResource(RecordsUIResource):
      pass
   
  # After
  from ccmm_invenio.ui.config import CCMMRecordsUIResourceConfig
  from ccmm_invenio.ui.resource import CCMMRecordsUIResource
   
  class DatasetsUIResourceConfig(CCMMRecordsUIResourceConfig):
      ...
   
  class DatasetsUIResource(CCMMRecordsUIResource):
      pass

  For a plain RDM-based model — inherit from RDMRecordsUIResourceConfig and RDMRecordsUIResource, imported from:

  • from oarepo_rdm.ui.config import RDMRecordsUIResourceConfig
  • from oarepo_rdm.ui.resource import RDMRecordsUIResource
  ui/<model_name>/__init__.py

  # Before
  from oarepo_ui.resources.records.config import RecordsUIResourceConfig
  from oarepo_ui.resources.records.resource import RecordsUIResource
   
  class DatasetsUIResourceConfig(RecordsUIResourceConfig):
      ...
   
  class DatasetsUIResource(RecordsUIResource):
      pass
   
  # After
  from oarepo_rdm.ui.config import RDMRecordsUIResourceConfig
  from oarepo_rdm.ui.resource import RDMRecordsUIResource
   
  class DatasetsUIResourceConfig(RDMRecordsUIResourceConfig):
      ...
   
  class DatasetsUIResource(RDMRecordsUIResource):
      pass

  If you compose components in your config, keep using *<NewBase>.components so the new RDM components are included.

• Search app: default two-column layout (oarepo-ui 13.0+, PR #460 ). The default search app layout changed for repositories whose search bar lives in the content area (not in the page header). The page is now rendered as a two-column layout: facets on the left, results on the right, with the search bar sitting in the right-hand column. If your repository keeps the search bar in the page header (Invenio’s default), the rendered page is unchanged and there is nothing to do.

  Old layout (search bar in content):

  

  New layout (search bar in content):

  

  Several exported search components were renamed or removed: ActiveFiltersElement → ActiveFilters, SearchAppResultOptions → ResultOptions, SearchAppSort → Sort; SearchAppLayoutWithSearchbarHOC and SearchAppResultViewWithSearchbar were removed (use SearchAppLayout directly). These changes only affect custom search code that imports the old component names directly — the copier-generated search/index.js is unaffected because it only uses parseSearchAppConfigs and createSearchAppsInit, which exist in both versions. A Scroll to top button is now rendered by default; if you do not want it, hide it via CSS (#scroll-to-top-button { display: none; }).

• invenio_url_for and Model.api_url no longer accept _external=True (oarepo-runtime 4.0.0+). Both helpers now always return an absolute (external) URL. Passing _external=True is no longer accepted and will raise (Model.api_url calls invenio_url_for under the hood and fails for the same reason). Drop _external=True from these calls — the returned URL is already absolute.

  # Before
  url = invenio_url_for("vocabularies.search", type="languages", _external=True)
  api = model.api_url("search", type=alias, _external=True)
   
  # After
  url = invenio_url_for("vocabularies.search", type="languages")
  api = model.api_url("search", type=alias)

4. Review community permission exception handling

From oarepo-communities 8.1.3 (shipped with oarepo-app 5.0.0) and 9.0.0 (shipped with oarepo-app 6.2.0), the community permission generators no longer raise MissingCommunitiesError or MissingDefaultCommunityError — they return an empty list instead. Both exception classes are deprecated — their constructors emit a DeprecationWarning.

If your code catches these exceptions, that branch is now dead code. Review and update it:

# These are deprecated and no longer raised by the community permission
# generators (OARepoCommunityRoles etc. return [] instead).
from oarepo_communities.errors import (
    MissingCommunitiesError,        # deprecated
    MissingDefaultCommunityError,   # deprecated
)
 
# Any branch like this is now dead code:
#     except MissingCommunitiesError: ...
# Handle the empty-list case directly instead.

Standard nrp-app-copier generated repositories do not catch these exceptions, so no action is needed for them.

5. Consider migrating to the simplified workflows

See simplified workflows for a more streamlined approach to workflow configuration.

Update pyproject.toml

In pyproject.toml, update the oarepo-app dependency extra from production to production,ccmm.

Before:

dependencies = [
    "oarepo-app[production]==4.0.0",
]

After:

dependencies = [
    "oarepo-app[production,ccmm]==4.0.0",
]

Run ./run.sh upgrade to update the lock file.

Update pyproject.toml

1. In pyproject.toml, remove all oarepo-* dependencies and replace them with the new oarepo-app library. Do not remove the oarepo[s3,rdm] dependency.

Before:

dependencies = [
        "oarepo[s3,rdm]>=14.0.0,<14.1.9",
        "oarepo-runtime>=2.0.0dev0,<3.0.0",
        "oarepo-ui>=7.0.0dev0,<8.0.0",
        ...
]

After:

dependencies = [
    "oarepo[s3,rdm]>=14.2.1b10.dev6,<15.0.0",
    "oarepo-app[production]==2.3.0",  # <---- here
]

2. Update the version of the oarepo library:

dependencies = [
    "oarepo[s3,rdm]>=14.2.1b10.dev6,<15.0.0",  # <---- here
    "oarepo-app[production]==2.3.0",
]

3. Make sure you use Python 3.14 in the requires-python section.

requires-python = ">=3.14,<3.15"

4. Remove the top-level package.json if it exists.

5. Run ./run.sh upgrade to update the lock file.

6. Run ./run.sh reset to reset your local instance because of the CCMM vocabularies.

7. If you have sample data, you will need to update it to use CCMM vocabularies. See your https://127.0.0.1:5000/vocabularies which values are permitted.

   For example:

   1. Change the resource type ID from dataset to c_ddb1.
   2. Change the created time reference to Created (capitalized first letter).
   3. Change the cc0-1.0 license to CC0-1.0 (capitalized CC).

For inspiration, see invenio-fzu PR #22 

Make sure you have run the older migrations first.

1. Move existing top-level models into models/

mv datasets models/

Repeat for every model that currently lives at the repository root.

2. Update invenio.cfg

Update the model import paths. For example, if you have a model called datasets:

# Before
from datasets import datasets_model
datasets_model.register()
 
# After
from models.datasets import datasets_model
datasets_model.register()

3. Update pyproject.toml

In the module-name section of pyproject.toml, remove the entry for the model folder you just moved (e.g. remove datasets). The model is now discovered from models/ automatically.

Option 1: Use model update (Recommended)

Run the model update command from your repository root:

./run.sh model update <model_name>

Option 2: Create files manually

If you prefer not to use model update, you can create the required template files manually in ui/mymodel/templates/semantic-ui/mymodel/. See the model copier template  for the complete list of required files.

Common issues:

• TemplateNotFound: mymodel/record_detail.html → Create base template file
• Partials not showing → Check that mymodel/record_detail/main.html exist