API Reference

This page is generated automatically from the docstrings in the oarepo_config source code, so it always matches the installed version of the package.

Top-level package

Everything below is what you get from import oarepo_config as config and call as config.configure_ui(...), config.configure_cron(...), etc. in invenio.cfg. This is the list of functions most people writing an invenio.cfg will actually use - see the README for a guided tour and a full example.

Helper functions for writing a clean, high-level invenio.cfg.

Instead of hand-assembling dozens of Flask/Invenio config constants, invenio.cfg calls a small number of configure_*() functions from this package. Each one computes a group of related settings and writes them directly into invenio.cfg’s own configuration, as if you had set them by hand:

import oarepo_config as config
from invenio_i18n import (
    lazy_gettext as _,
)

config.initialize_i18n()

config.configure_generic_parameters(
    languages=(("cs", _("Czech")),),
)

config.configure_ui(
    code="myrepo",
    name=_("My repository"),
    description=_(
        "Description of my repository"
    ),
)

config.configure_communities()
config.configure_cron()
config.configure_stats()

# Feel free to add/override plain CONFIG_VARIABLE = value assignments
# below, or use config.configure_vocabulary(...), config.add_model(...),
# config.register_workflow(...), etc. for further options.

See the project’s README for the full list of available functions, the order they should be called in, and the environment variables they read.

class oarepo_config.CommunityWorkflow(code='undefined', label=l'Undefined policy', base_permission_policy=<class 'oarepo_config.workflows.simplified.workflow_permissions.DefaultRDMWorkflowPermissions'>, base_request_policy=<class 'oarepo_workflows.requests.policy.WorkflowRequestPolicy'>, review_request_states=<factory>, record_view_permissions=<factory>, publish_after_review=True, extra_permissions=None, extra_requests=None, authenticated_draft_creation=False, draft_creation_roles=<factory>, draft_creation_needs=<factory>, draft_creation_community_roles=<factory>, read_restricted_community_roles=<factory>, read_draft_community_roles=<factory>, record_manage_community_roles=<factory>, community_curator_roles=<factory>)[source]

Bases: BaseWorkflowSettings

Workflow configuration for deposits inside communities.

draft_creation_community_roles: list[str]

Restrict draft creation to community members with at least one of these roles.

If not specified (empty list), any member of the community can create a draft. Used in addition to the site-wide draft_creation_roles / draft_creation_needs restrictions.

read_restricted_community_roles: list[str]

Community roles that may read restricted (published) records without requesting access.

If empty, only the record owner can read the content after publishing. By default allowing curators and community owners to access restricted records.

Note

Community roles are used instead of RecordCommunitiesAction so that each workflow can have independent read/draft/manage permissions.

read_draft_community_roles: list[str]

Community roles that may read draft records without requesting access.

If empty, only the record owner can read the content of a draft. Curators can always read draft records when the record is submitted for review.

Note

Community roles are used instead of RecordCommunitiesAction so that each workflow can have independent read/draft/manage permissions.

record_manage_community_roles: list[str]

Community roles that may manage (edit, delete, publish) records.

If empty, only the record owner can manage the record. By default allowing curators and community owners to manage all records.

Note

Community roles are used instead of RecordCommunitiesAction so that each workflow can have independent read/draft/manage permissions.

community_curator_roles: list[str]

Community roles that allow users to review and curate records.

class oarepo_config.IndividualWorkflow(code='individual', label=l'Individual Submission Workflow', base_permission_policy=<class 'oarepo_config.workflows.simplified.workflow_permissions.DefaultRDMWorkflowPermissions'>, base_request_policy=<class 'oarepo_workflows.requests.policy.WorkflowRequestPolicy'>, review_request_states=<factory>, record_view_permissions=<factory>, publish_after_review=True, extra_permissions=None, extra_requests=None, authenticated_draft_creation=True, draft_creation_roles=<factory>, draft_creation_needs=<factory>, publish_without_review=False, publish_without_review_roles=<factory>, publish_without_review_needs=<factory>, publish_without_review_states=<factory>, review_required=False, reviewer_roles=<factory>, reviewer_needs=<factory>, self_review_enabled=False)[source]

Bases: BaseWorkflowSettings

Workflow configuration for deposits outside of communities.

authenticated_draft_creation: bool = True

Allow authenticated users to create drafts in this workflow.

Overrides the base-class default of False; any authenticated user can create a draft unless more-specific role or need restrictions are configured via draft_creation_roles or draft_creation_needs.

code: str = 'individual'

Unique code identifier for this workflow.

label: LazyString = l'Individual Submission Workflow'

Human-readable label for this workflow.

publish_without_review: bool = False

Allow draft owners to publish without submitting a review request.

When enabled, draft owners can publish directly, subject to publish_without_review_states.

record_owners_with_correct_roles(record_owner_generator)[source]

Return the record owner generator with the correct roles/needs.

review_required: bool = False

Require a review request before publication.

If publish_without_review is False and review_required is False, records can only be published through a community workflow.

self_review_enabled: bool = False

Allow the record owner to approve their own review request.

Normally, submitting a record for review prevents the owner from approving it themselves. When set to True, the review request is still created on submission, but the owner is permitted to accept it.

This is primarily useful when invenio-checks is active: checks are tied to an open request, so the request must exist even when no external reviewer is needed. With this option the owner can see and act on the check results without waiting for a curator.

Has no effect when publish_without_review is True, because in that case user can bypass the review request and publish the record directly.

publish_without_review_roles: list[str]

Roles that allow a draft owner to publish without a review request.

Users must still be owners of the draft record. If the list is non-empty, publish_without_review is ignored.

publish_without_review_needs: list[str]

Permission needs that allow a draft owner to publish without a review request.

Users must still be owners of the draft record. If the list is non-empty, publish_without_review is ignored.

publish_without_review_states: list[str]

Record workflow states in which publication without review is allowed.

reviewer_roles: list[str]

Roles that allow users to review and curate records.

Users with these roles are also granted read access to draft records.

reviewer_needs: list[str]

Permission needs that allow users to review and curate records.

Users with these needs are also granted read access to draft records.

oarepo_config.add_model(model_package_name)[source]

Include a data model in the repository’s global (cross-model) search.

Repositories can host several different kinds of records (models), e.g. “datasets” and “publications”. Call this once per model package to make its records show up in searches that span all models at once (as opposed to searching within just one model). This does not register the model itself (its API endpoints, forms, etc.) - that is normally done separately, by calling that model package’s own register() function.

Parameters:

model_package_name (str) – The Python import path of the generated model package to add, e.g. "datasets" for a model built from a datasets model package. If the package cannot be found or has not been built yet, this is only logged as an error - it does not stop the repository from starting.

Invenio configuration variables set:

  • GLOBAL_SEARCH_MODELS - the model’s MODEL_DEFINITION is appended to this list; any models already registered (by earlier calls, or by other packages) are kept.

Example:

from datasets import datasets_model

datasets_model.register()
config.add_model("datasets")
oarepo_config.configure_communities(communities_roles=None)[source]

Set up the configuration for communities.

Communities let you organize records into collections with their own managers and settings. This function configures who can do what in each community (the roles), how records are submitted to communities, and other community-related settings.

Parameters:

communities_roles (list | None) – Custom role definitions for communities. If not provided, defaults to owner/curator/member roles. If omitted, three default roles are used: “owner” (can manage the community and its members), “curator” (can review/curate submitted records) and “member” (can only view). Pass your own list to replace the defaults, e.g. to add a “submitter” role. Each role dictionary understands the keys name, title, description, is_owner, can_manage, can_curate and can_manage_roles (the names of the roles this role is allowed to add/remove).

Invenio configuration variables set:

  • COMMUNITIES_REGISTER_UI_BLUEPRINT - always True; enables the communities UI.

  • COMMUNITIES_PERMISSION_POLICY - the permission policy class for communities.

  • COMMUNITIES_ROLES - the list of available roles in communities.

Example:

config.configure_communities()
# or with custom settings:

config.configure_communities(
    communities_roles=[
        dict(
            name="owner",
            title=_("Community owner"),
            is_owner=True,
            can_manage=True,
            can_manage_roles=[
                "owner",
                "curator",
                "member",
                "submitter",
            ],
        ),
        dict(
            name="curator",
            title=_("Curator"),
            can_manage=True,
            can_manage_roles=[
                "member",
                "submitter",
            ],
        ),
        dict(
            name="submitter",
            title=_("Submitter"),
            can_manage=True,
        ),
        dict(
            name="member",
            title=_("Member"),
        ),
    ]
)
oarepo_config.configure_cron(**extra_cron_items)[source]

Set up the periodic (scheduled) background tasks the repository needs.

The repository relies on a number of jobs that must run automatically in the background on a regular basis - for example, cleaning up old sessions, aggregating usage statistics, or clearing caches. This function sets up a sensible set of such jobs out of the box:

  • keeping the search index queues healthy (every 10 seconds)

  • cleaning up expired user sessions and old IP address logs

  • processing and aggregating usage statistics (hourly)

  • clearing the communities cache (daily)

  • removing expired file-access-request tokens (daily)

Parameters:

**extra_cron_items (Any) –

Additional scheduled jobs to add (or to override, if the name matches one of the built-in jobs above), one keyword per job. Each value follows Celery’s “beat schedule” format, e.g.:

config.configure_cron(
    my_job={
        "task": "my_package.tasks.my_task",
        "schedule": timedelta(
            minutes=30
        ),
    },
)

Invenio configuration variables set:

  • CELERY_BEAT_SCHEDULE - merged with any schedule already defined earlier in invenio.cfg; entries from **extra_cron_items win over the built-in defaults listed above when their names collide.

oarepo_config.configure_datastreams(readers=None, writers=None, transformers=None)[source]

Register custom sources for importing vocabularies (fixtures) into the repository.

Vocabularies (controlled lists such as languages, resource types or licenses) can be loaded from files or external services using “datastreams” - a reader that fetches/reads the raw data, an optional transformer that converts it, and a writer that stores it. Invenio already ships with a set of built-in readers/writers/ transformers; use this function only if you need to add your own (for example, a reader that pulls a vocabulary from a custom REST API).

Parameters:

  • readers (dict[str, Any] | None) – Extra readers to make available, as a mapping of a short name to either an import path string ("my_package.readers:MyReader") or the class/object itself.

  • writers (dict[str, Any] | None) – Extra writers to make available, in the same format as readers.

  • transformers (dict[str, Any] | None) – Extra transformers to make available, in the same format as readers.

Any readers/writers/transformers already registered (for example by configure_generic_parameters()) are kept; the ones passed here are added on top.

Invenio configuration variables set:

  • VOCABULARIES_DATASTREAM_READERS - only if readers is given; merged with any existing value.

  • VOCABULARIES_DATASTREAM_WRITERS - only if writers is given; merged with any existing value.

  • VOCABULARIES_DATASTREAM_TRANSFORMERS - only if transformers is given; merged with any existing value.

Example:

config.configure_datastreams(
    readers={
        "myreader": "my_package:MyReader"
    },
    writers={
        "mywriter": "my_package:MyWriter"
    },
)
oarepo_config.configure_einfra_oidc()[source]

Set up “Log in with e-INFRA” (CESNET/Perun) for the repository.

This enables single sign-on through the CESNET e-INFRA identity provider, so users can log in with their e-INFRA/Perun account instead of (or in addition to) a local username and password. It also makes user profile information (name, e-mail, …) read-only locally, since it is then managed by e-INFRA instead.

Requires the optional oarepo-oidc-einfra package to be installed - if it is missing, this function prints a message and stops the application from starting.

Whether e-INFRA login is actually turned on is controlled by the INVENIO_REMOTE_AUTH_ENABLED setting (true/yes/1 to enable it, anything else - including leaving it unset - disables it). When enabled, the client credentials INVENIO_EINFRA_CONSUMER_KEY and INVENIO_EINFRA_CONSUMER_SECRET must also be provided (see the deployment’s variables/.env configuration).

Invenio configuration variables set:

  • OAUTHCLIENT_REMOTE_APPS - always updated (merged with any existing value); gets an "e-infra" entry only when e-INFRA login is enabled.

  • EINFRA - only when e-INFRA login is enabled; the e-INFRA client credentials and endpoint configuration.

  • USERPROFILES_READ_ONLY - only when e-INFRA login is enabled; forced to True.

Example:

config.configure_einfra_oidc()

Make sure to set INVENIO_REMOTE_AUTH_ENABLED=true and provide INVENIO_EINFRA_CONSUMER_KEY and INVENIO_EINFRA_CONSUMER_SECRET in your deployment’s variables or environment.

oarepo_config.configure_files(max_file_size=10000000000, max_files_count=100, max_total_size=10000000000, allow_metadata_only_records=True)[source]

Set up file upload quotas and the metadata-only records toggle.

Controls how many files users may attach to a record deposition, how large each individual file may be, the total storage budget for the deposition, and whether a deposition can be published without any files at all.

Parameters:

  • max_file_size (int) – Maximum size of a single uploaded file in bytes. Defaults to 10 GB (10 * 10**9).

  • max_files_count (int) – Maximum number of files allowed per record deposition. Defaults to 100.

  • max_total_size (int) – Maximum combined size of all files in a single record deposition, in bytes. Defaults to 10 GB (10 * 10**9).

  • allow_metadata_only_records (bool) – When False, users must upload at least one file before they can publish a record deposition. When True (the default), metadata-only records are allowed.

Invenio configuration variables set:

  • RDM_FILES_DEFAULT_MAX_FILE_SIZE - backend limit on the size of a single file.

  • RDM_FILES_DEFAULT_QUOTA_SIZE - backend limit on the total size of all files in a record deposition.

  • RDM_RECORDS_MAX_FILES_COUNT - backend limit on the number of files per record.

  • RDM_ALLOW_METADATA_ONLY_RECORDS - whether metadata-only records are allowed.

  • APP_RDM_DEPOSIT_FORM_QUOTA - deposit-form UI quota object with maxFiles and maxStorage.

  • FILES_REST_DEFAULT_MAX_FILE_SIZE and FILES_REST_DEFAULT_QUOTA_SIZE - fallback variables used by the lower-level file storage layer.

Example:

# Require at least one file per record, with a 5 GB total budget
# and files no larger than 1 GB each.
config.configure_files(
    max_file_size=1 * 10**9,
    max_files_count=20,
    max_total_size=5 * 10**9,
    allow_metadata_only_records=False,
)
oarepo_config.configure_generic_parameters(languages=(('en', 'English'),), use_path_pid_ids=False)[source]

Set up the core, infrastructure-level configuration of the repository.

This is the main “plumbing” function that should normally be called first, before any of the other configure_* functions. It reads most of its values from the deployment’s environment configuration (the variables/.env files or process environment variables, all prefixed with INVENIO_) and uses them to configure:

  • the site’s public URLs, and allowed security headers

  • whether local login/registration/password-reset is available

  • the database, search engine (OpenSearch), file storage (S3), cache and message queue (Redis/RabbitMQ) connections

  • translation/locale and file-upload defaults

  • default identifier schemes recognised for names, funders and affiliations (e.g. ORCID, ROR, VEDIDK, Scopus author ID)

Because most values come from the environment, this function will fail to start the application if a required INVENIO_... variable is missing from the deployment’s configuration - see the project’s README for the full list of variables it expects.

Parameters:

  • languages (tuple[tuple[str, str], ...]) – Extra UI languages to offer, as a tuple of (language_code, label) pairs, e.g. (("cs", _("Czech")), ("de", _("German"))). English is always available and does not need to be listed.

  • use_path_pid_ids (bool) – Set this to True only if your repository uses record identifiers that themselves contain a slash (/); it adjusts the URLs used for managing record access so that such identifiers keep working.

Invenio configuration variables set, grouped by area:

Public URLs & security headers

  • APP_ALLOWED_HOSTS

  • SITE_UI_URL, SITE_API_URL

  • APP_DEFAULT_SECURE_HEADERS

Local login & accounts

  • ACCOUNTS_LOCAL_LOGIN_ENABLED, SECURITY_REGISTERABLE, SECURITY_RECOVERABLE, SECURITY_CHANGEABLE, SECURITY_CONFIRMABLE, SECURITY_LOGIN_WITHOUT_CONFIRMATION

  • SESSION_COOKIE_SECURE

  • RATELIMIT_GUEST_USER, RATELIMIT_AUTHENTICATED_USER

  • OAUTHCLIENT_REMOTE_APPS - starts out empty here; extended by configure_einfra_oidc() if used.

  • ACCOUNTS_LOGIN_VIEW_FUNCTION, OAUTHCLIENT_AUTO_REDIRECT_TO_EXTERNAL_LOGIN

Database

  • SQLALCHEMY_DATABASE_URI

Translation/locale

  • BABEL_DEFAULT_LOCALE, BABEL_DEFAULT_TIMEZONE, I18N_LANGUAGES

Files & storage

  • SEND_FILE_MAX_AGE_DEFAULT, FILES_REST_STORAGE_FACTORY

  • S3_ENDPOINT_URL, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY

  • FILES_REST_STORAGE_CLASS_LIST, FILES_REST_DEFAULT_STORAGE_CLASS, FILES_REST_DEFAULT_QUOTA_SIZE

  • APP_RDM_DEPOSIT_FORM_QUOTA

User profiles

  • USERPROFILES_READ_ONLY

OAI-PMH

  • OAISERVER_ID_PREFIX

Search (OpenSearch)

  • SEARCH_INDEX_PREFIX, SEARCH_HOSTS, SEARCH_CLIENT_CONFIG

  • VOCABULARIES_SERVICE_CONFIG, VOCABULARIES_RESOURCE_CONFIG - only if the optional oarepo_vocabularies package is installed.

Caches (Redis)

  • INVENIO_CACHE_TYPE, CACHE_REDIS_URL, ACCOUNTS_SESSION_REDIS_URL, COMMUNITIES_IDENTITIES_CACHE_REDIS_URL

Background jobs (Celery/RabbitMQ)

  • CELERY_BROKER_URL, BROKER_URL, CELERY_RESULT_BACKEND

JSON schemas

  • RECORDS_REFRESOLVER_CLS, RECORDS_REFRESOLVER_STORE, JSONSCHEMAS_HOST

Secrets

  • SECRET_KEY

Records/REST compatibility

  • DASHBOARD_RECORD_CREATE_URL, RECORD_ROUTES, RECORDS_REST_ENDPOINTS

DataCite/DOIs

  • DATACITE_TEST_MODE

Mail

  • MAIL_DEFAULT_SENDER

  • MAIL_SUPPRESS_SEND - only if INVENIO_MAIL_SUPPRESS_SEND is set in the environment.

Identifier/name/funder/affiliation vocabularies

  • VOCABULARIES_NAMES_SCHEMES, VOCABULARIES_FUNDER_SCHEMES, VOCABULARIES_AFFILIATION_SCHEMES - merged with any existing value.

  • APP_RDM_IDENTIFIER_SCHEMES_UI

  • VOCABULARIES_DATASTREAM_READERS, VOCABULARIES_DATASTREAM_WRITERS, VOCABULARIES_DATASTREAM_TRANSFORMERS - seeded from invenio-app-rdm’s defaults, merged with any existing value; see configure_datastreams() to add your own.

Miscellaneous

  • ROR_CLIENT_ID, SESSION_COOKIE_DOMAIN, COLLECT_STORAGE

In addition, if use_path_pid_ids is True, this patches the url_prefix of RDMParentRecordLinksResourceConfig, RDMParentGrantsResourceConfig, RDMGrantUserAccessResourceConfig and RDMGrantGroupAccessResourceConfig directly - this is a class attribute change, not a new invenio.cfg variable.

Example:

config.configure_generic_parameters(
    languages=(
        ("cs", _("Czech")),
        ("de", _("German")),
    ),
)
oarepo_config.configure_jobs(permission_policy=None, logging_level=None)[source]

Set up the “Jobs” feature (manually or automatically run administrative tasks).

Invenio-jobs lets administrators run and monitor maintenance tasks (such as re-indexing or fixing up data) from the admin panel, and view their logs. This decides who is allowed to view those job logs and how detailed the logs are.

Parameters:

  • permission_policy (str | type | None) – Who is allowed to view job logs. By default, only administrators can. Pass your own permission policy class (or its import path as a string) to change this.

  • logging_level (str | None) – How detailed the job logs should be, e.g. "DEBUG", "INFO" (the default), "WARNING".

Invenio configuration variables set:

  • APP_LOGS_PERMISSION_POLICY - the permission_policy above.

  • JOBS_LOGGING_LEVEL - the logging_level above.

Example:

config.configure_jobs()
# or with custom settings:
config.configure_jobs(
    permission_policy="my_package:policies:MyJobPolicy",
    logging_level="DEBUG",
)
oarepo_config.configure_llm(api_token=None, *, enabled=True, client_name='chat_einfra', api_url='https://llm.ai.e-infra.cz/v1/chat/completions', model='gpt-oss-120b', fallback_community=None, as_default=True)[source]

Set up the LLM client(s) used by oarepo-checks’ AI-assisted record validation.

oarepo-checks can validate a record’s metadata by sending it to a Large Language Model and checking the response (its "llm" check, shown to users as “AI validation”) before a record may be published. This registers one such LLM client (built-in support is for chat.ai.e-infra.cz) that the check can use.

Call it once per LLM client/token you want available - each call reads back and extends whatever a previous call already registered (via get_constant_from_caller()), it does not replace it. This also means, when calling it more than once, that whichever call has ``as_default=True`` last wins as the default client.

Requires the optional oarepo-checks package to be installed; without it, calling this raises an ImportError explaining that the package needs to be installed first.

Parameters:

  • api_token (str | None) – Bearer token for the ChatEInfraClient (chat.ai.e-infra.cz). If not given, this call only touches CHECKS_ENABLED/CHECKS_GENERIC_COMMUNITY/the default client marker below, without registering a new client under client_name. Typically read from the deployment’s variables/.env/environment via load_configuration_variables(), not hardcoded.

  • enabled (bool) – Set to False to skip configuring the LLM subsystem entirely (nothing else below is set).

  • client_name (str) – The key this client is registered under in OAREPO_CHECKS_LLM_CLIENTS. Use a different name per call if you are registering more than one client.

  • api_url (str) – The ChatEInfraClient API endpoint to send requests to.

  • model (str) – The model name the ChatEInfraClient requests.

  • fallback_community (str | None) – Slug of the community used for checks that aren’t tied to a specific community. If given, overrides whatever a previous call already set; if not given, an already-set value is kept, defaulting to "llm-settings-community" if no call has provided one yet.

  • as_default (bool) – Mark client_name as the client checks use when they don’t request one by name (OAREPO_CHECKS_DEFAULT_LLM_CLIENT).

Invenio configuration variables set:

  • CHECKS_ENABLED - the enabled argument above.

  • OAREPO_CHECKS_LLM_CLIENTS - only if enabled; extended (not replaced) with a ChatEInfraClient entry under client_name, only if api_token was given.

  • OAREPO_CHECKS_DEFAULT_LLM_CLIENT - only if enabled and as_default; set to client_name.

  • CHECKS_GENERIC_COMMUNITY - only if enabled; fallback_community if given, else an already-set value, else "llm-settings-community".

Example:

env = config.load_configuration_variables()
config.configure_llm(
    api_token=env.get(
        "INVENIO_LLM_API_TOKEN"
    )
)

# registering a second, non-default client:
config.configure_llm(
    api_token=env.get(
        "INVENIO_LLM_BACKUP_API_TOKEN"
    ),
    client_name="chat_einfra_backup",
    as_default=False,
)
oarepo_config.configure_oai()[source]

Set up OAI-PMH, the protocol other systems use to harvest records from this repository.

OAI-PMH is a standard way for external services (e.g. national aggregators, other repositories) to regularly fetch a list of published records. This announces the repository’s name over that protocol, using the name already set via configure_ui().

Takes no parameters. Must be called after configure_ui(), since it needs the repository name that function sets up; calling it earlier raises an error explaining this.

Invenio configuration variables set:

  • OAISERVER_REPOSITORY_NAME - copied from REPOSITORY_NAME (set by configure_ui()).

Example:

config.configure_oai()
oarepo_config.configure_stats(enable=True)[source]

Set up usage statistics (record views, downloads, etc.).

Enables the collection and aggregation of usage events, such as how many times a record was viewed or a file was downloaded, so this data can later be shown to users and curators.

Parameters:

enable (bool) – Set to False to turn off collecting new usage statistics events (for example on a staging/test instance). Defaults to True.

Invenio configuration variables set:

  • STATS_REGISTER_RECEIVERS - the enable argument above.

  • STATS_EVENTS, STATS_AGGREGATIONS, STATS_QUERIES, STATS_PERMISSION_FACTORY - always set to invenio-app-rdm’s defaults, regardless of enable.

Example:

config.configure_stats()
# or on a test instance:
config.configure_stats(enable=False)
oarepo_config.configure_ui(code='myrepo', name='My Repository', subtitle='', description='', support_contact='', keywords='', use_default_frontpage=False, show_frontpage_intro=True, analytics=False, languages=(('en', 'English'),))[source]

Set up the repository’s branding, name and general look-and-feel.

Configures what visitors see: the repository’s name and description shown in the browser tab/search results/front page, the theme, the page layout templates, and (optionally) analytics tracking.

Parameters:

  • code (str) – A short, technical, all-lowercase identifier for this repository (e.g. "myrepo"); used internally to select the repository’s own theme files.

  • name (str | Any) – The repository’s display name, shown in the browser title and on the front page, e.g. _("My Repository").

  • subtitle (str) – A short subtitle/tagline shown next to the name.

  • description (str) – A longer description of the repository, used for SEO and on the front page.

  • support_contact (str) – Contact information (e.g. an e-mail address) shown to users who need help.

  • keywords (str) – Keywords describing the repository’s content, used for SEO.

  • use_default_frontpage (bool) – Whether to use Invenio’s generic front page. Most repositories provide a custom front page, so this defaults to False.

  • show_frontpage_intro (bool) – Whether to show the introductory text section on the front page.

  • analytics (str | bool) – Set to "matomo" to enable Matomo web analytics tracking (only takes effect on deployed, non-local instances; requires the Matomo URL/site ID to be configured in the deployment’s environment). False (the default) disables analytics.

  • languages (tuple[tuple[str, str], ...]) – Extra UI languages to offer, as a tuple of (language_code, label) pairs. English is always available and does not need to be listed. This should normally match what was passed to configure_generic_parameters().

Should be called after configure_generic_parameters() (it builds on settings that function prepares) and before configure_oai() (which needs the repository name set here).

Example:

config.configure_ui(
    code="myrepo",
    name=_("My Repository"),
    description=_(
        "A repository for my data"
    ),
    support_contact="support@example.com",
)

Invenio configuration variables set, grouped by area:

Versioning

  • DEPLOYMENT_VERSION

Theme & security
Page layout templates

  • INSTANCE_THEME_FILE

  • BASE_TEMPLATE, ADMINISTRATION_THEME_BASE_TEMPLATE, COVER_TEMPLATE

  • THEME_CSS_TEMPLATE, THEME_JAVASCRIPT_TEMPLATE

  • HEADER_TEMPLATE, THEME_HEADER_TEMPLATE, THEME_HEADER_LOGIN_TEMPLATE, THEME_FOOTER_TEMPLATE

  • THEME_TRACKINGCODE_TEMPLATE, THEME_FRONTPAGE_TEMPLATE

  • SETTINGS_TEMPLATE, SEARCH_UI_SEARCH_TEMPLATE

Analytics

  • MATOMO_ANALYTICS_TEMPLATE, MATOMO_ANALYTICS_URL, MATOMO_ANALYTICS_SITE_ID - only if analytics="matomo" and this is not a local-development deployment.

Branding

  • THEME_FRONTPAGE, THEME_LOGO, THEME_FRONTPAGE_LOGO

  • THEME_SITENAME, THEME_FRONTPAGE_TITLE, THEME_SHOW_FRONTPAGE_INTRO_SECTION

Repository metadata (SEO & front page)

  • REPOSITORY_NAME, REPOSITORY_DESCRIPTION, REPOSITORY_SUPPORT_CONTACT, REPOSITORY_SUBTITLE, REPOSITORY_KEYWORDS

Build pipeline

  • JAVASCRIPT_PACKAGES_MANAGER, ASSETS_BUILDER, WEBPACKEXT_NPM_PKG_CLS, WEBPACKEXT_PROJECT

Records & deposit UI

  • RECORDS_UI_ENDPOINTS, APP_RDM_DEPOSIT_NG_FILES_UI_ENABLED, DASHBOARD_RECORD_CREATE_URL

  • APP_RDM_DETAIL_SIDE_BAR_TEMPLATES

Search UI

  • THEME_SEARCH_ENDPOINT, SEARCH_UI_SEARCH_VIEW

oarepo_config.configure_vocabulary(code, **kwargs)[source]

Declare a custom controlled vocabulary (a fixed list of allowed values).

Vocabularies are controlled lists of values that records can pick from, such as languages, resource types or licenses. Call this once for each additional vocabulary type your repository needs, to describe it and any extra properties it should have.

Parameters:

  • code (str) – A short, unique identifier for the vocabulary, e.g. "languages".

  • **kwargs (Any) – Extra details describing the vocabulary, typically including name (its display name), description, and props (a description of any extra fields each entry in the vocabulary should have, and how they appear in forms). See the OARepo reference docs for the full list of supported keys.

Calling this multiple times with different code values adds multiple vocabularies; it does not replace previously configured ones.

Invenio configuration variables set:

  • INVENIO_VOCABULARY_TYPE_METADATA - the entry for code is set to kwargs; entries for other vocabulary codes (added by earlier calls) are kept.

Example:

config.configure_vocabulary(
    code="languages",
    name=_("Languages"),
    description=_(
        "Language definitions"
    ),
    props={
        "alpha3Code": {
            "description": _(
                "ISO 639-2 standard 3-letter language code"
            ),
            "multiple": False,
            "search": False,
        },
    },
    dump_options=True,
)
oarepo_config.configure_workflows(*workflow_definitions, default_individual_workflow='individual', default_community_workflow='community', context=None)[source]

Set up workflows based on the provided workflow definitions.

This function is intended to be called from within invenio.cfg and will create a “WORKFLOWS” entry in the invenio.cfg context (in the caller’s globals).

Example

# invenio.cfg
from oarepo_app.config import (
    configure_workflows,
    IndividualWorkflow,
    CommunityWorkflow,
)

configure_workflows(
    IndividualWorkflow(
        authenticated_draft_creation=False,
        review_required=True,
        publish_without_review=False,
    ),
    CommunityWorkflow(),
)
# no need to assign the result to WORKFLOWS, that is done automatically

If the workflow definitions are empty, a permissive IndividualWorkflow will be created (authenticated draft creation, publish without review allowed).

If there is no IndividualWorkflow definition in the workflow definitions (but there are other workflow types), a restricted IndividualWorkflow (no deposition allowed) will be created with default settings.

The default_individual_workflow parameter should be the code of the workflow to use as the default one for individual deposits, where no community is involved and the workflow code is not provided by the caller.

If the context is provided, the “WORKFLOWS” entry will be added to it instead of the caller’s globals.

See https://nrp-cz.github.io/docs/customize/workflows for more information on how to customize the workflows.

oarepo_config.initialize_glitchtip(dsn=None, deployment_version=None)[source]

Initialize glitchtip.

Parameters:

  • dsn (str | None) – Sentry DSN. If not passed, it is taken from INVENIO_GLITCHTIP_DSN environment variable.

  • deployment_version (str | None) – [optional] Deployment version. If not passed, it is taken from DEPLOYMENT_VERSION environment variable.

oarepo_config.initialize_i18n()[source]

Enable translated validation error messages.

Makes sure that when a user submits invalid data (for example, a required field is missing), the error message shown to them is translated into their chosen language instead of always being shown in English. Takes no parameters; call it once, near the top of invenio.cfg.

Invenio configuration variables set: none - this only patches Marshmallow’s error-message machinery in memory.

Example:

config.initialize_i18n()
oarepo_config.load_configuration_variables()[source]

Read the deployment’s configuration values (INVENIO_... variables).

Collects configuration values set by the deployment, from multiple places, each one able to override the previous (lowest to highest priority):

  1. a variables file next to invenio.cfg (the instance directory);

  2. a variables file in the current working directory;

  3. a .env file in the current working directory;

  4. any .json/.yaml/.yml files under the directory named by the INVENIO_CONFIG_PATH environment variable, if set;

  5. the actual process environment variables (always wins).

Values such as "True"/"False" or JSON snippets are converted to real Python types (booleans, numbers, lists, dicts) where possible. The result can be accessed both as a dictionary and via attribute access (e.g. env.INVENIO_SECRET_KEY); accessing a variable that was never set raises AttributeError.

oarepo_config.override_configuration(env=None)[source]

Apply ad-hoc configuration overrides from the environment, without writing Python code.

Lets a deployment set (or override) any Invenio configuration value directly from the variables/.env files or the process environment, by prefixing its name with INVENIO_. For example, setting INVENIO_RDM_ARCHIVE_DOWNLOAD_ENABLED=false in the deployment’s configuration will set the RDM_ARCHIVE_DOWNLOAD_ENABLED setting to False, without needing to change invenio.cfg.

This is not applied automatically - call it explicitly from invenio.cfg, typically as the very last step, so that these overrides win over anything set by the configure_*() functions above it.

Parameters:

env (dict[str, Any] | None) – Normally left unset, in which case the values loaded from variables/.env/the process environment are used.

oarepo_config.register_workflow(workflow_code, workflow_name, permissions_policy, requests_policy, use_low_level_workflows=False)[source]

Register a submission/review workflow that records can go through.

A workflow defines the path a record takes from being created to being published - for example, who may create it, whether it needs review/approval before publishing, and who may perform each of those steps. This adds one such workflow to the repository, so that it can be selected when configuring where records may be submitted (e.g. a community).

This is a low-level, single-workflow building block. Repositories that use the community-based workflow shape provided by the oarepo_app package typically use its higher-level configure_workflows(IndividualWorkflow(...), CommunityWorkflow(...)) helper instead - see this package’s README for the difference.

Parameters:

  • workflow_code (str) – A short, unique identifier for the workflow, e.g. "default".

  • workflow_name (str | Any) – The human-readable name of the workflow, shown to users, e.g. _("Default workflow").

  • permissions_policy (str | type) – Who is allowed to do what with records that use this workflow (create, edit, delete, publish, …). Pass either a permissions policy class or its import path as a string.

  • requests_policy (str | type) – What review/approval requests are available for records using this workflow (e.g. a publish request that needs a curator’s approval). Pass either a request policy class or its import path as a string.

  • use_low_level_workflows (bool) – Set to True to silence the warning recommending configure_workflows() instead, for the (uncommon) cases that genuinely need this low-level, single-workflow API.

Requires the optional oarepo_workflows (and, for its defaults, oarepo_requests) package to be installed.

Invenio configuration variables set:

  • WORKFLOWS - the new workflow is appended; workflows already registered (by earlier calls) are kept.

  • REQUESTS_PERMISSION_POLICY - only if not already set by an earlier call; defaults to CreatorsFromWorkflowRequestsPermissionPolicy.

Example:

from oarepo_workflows.services.permissions import (
    DefaultWorkflowPermissions,
)
from oarepo_requests.services.permissions.workflow_policies import (
    CreatorsFromWorkflowRequestsPermissionPolicy,
)

config.register_workflow(
    workflow_code="default",
    workflow_name=_("Default workflow"),
    permissions_policy=DefaultWorkflowPermissions,
    requests_policy=CreatorsFromWorkflowRequestsPermissionPolicy,
)

Module reference

The sections below document every module individually, including internal helpers that are not re-exported from the top-level oarepo_config package. This is mostly useful if you are extending oarepo_config itself, or writing your own configure_*()-style helper following the same pattern.

oarepo_config.base

The low-level machinery (environment-variable loading, and the “write constants into invenio.cfg” mechanism) that every configure_*() function is built on top of.

Base configuration utilities for oarepo-config.

oarepo_config.base.set_constants_in_caller(constants)[source]

Set the constants in the caller’s globals.

Example: mymodule:

import config

config.doit()
print(MY_CONSTANT)

config:

def doit():
    set_constants_in_caller(
        {"MY_CONSTANT": 42}
    )
oarepo_config.base.get_constant_from_caller(name, default=None)[source]

Get constant from the caller frame and optionally return a default value if not found.

Example: mymodule:

import config

MY_CONSTANT = 42
config.doit()

config:

def doit():
    # prints 42
    print(
        get_constant_from_caller(
            "MY_CONSTANT", 20
        )
    )
oarepo_config.base.merge_with_caller(name, to_merge)[source]

Merge the given value with an existing caller global of the same name.

oarepo_config.base.get_invenio_cfg_path()[source]

Get the path to the invenio.cfg file.

oarepo_config.base.load_configuration_overrides()[source]

Read deployment configuration values from the current directory and the process environment.

This is the part of load_configuration_variables() that does not depend on the location of invenio.cfg: it merges, lowest to highest priority, a variables file in the current working directory, a .env file in the current working directory, any .json/.yaml/.yml files under the directory named by the INVENIO_CONFIG_PATH environment variable (if set), and finally the actual process environment variables whose name starts with INVENIO_.

class oarepo_config.base.DictWithGetAttr[source]

Bases: dict

Dictionary that allows access to its items as attributes.

oarepo_config.base.load_configuration_variables()[source]

Read the deployment’s configuration values (INVENIO_... variables).

Collects configuration values set by the deployment, from multiple places, each one able to override the previous (lowest to highest priority):

  1. a variables file next to invenio.cfg (the instance directory);

  2. a variables file in the current working directory;

  3. a .env file in the current working directory;

  4. any .json/.yaml/.yml files under the directory named by the INVENIO_CONFIG_PATH environment variable, if set;

  5. the actual process environment variables (always wins).

Values such as "True"/"False" or JSON snippets are converted to real Python types (booleans, numbers, lists, dicts) where possible. The result can be accessed both as a dictionary and via attribute access (e.g. env.INVENIO_SECRET_KEY); accessing a variable that was never set raises AttributeError.

oarepo_config.base.transform_value(x)[source]

Convert string from environment to python type.

oarepo_config.base.find_files(directory, extension)[source]

Find all files with the given extension in the directory.

oarepo_config.base.load_config_from_directory(config_dir, env)[source]

Load configuration from JSON/YAML files in the given directory.

oarepo_config.base.override_configuration(env=None)[source]

Apply ad-hoc configuration overrides from the environment, without writing Python code.

Lets a deployment set (or override) any Invenio configuration value directly from the variables/.env files or the process environment, by prefixing its name with INVENIO_. For example, setting INVENIO_RDM_ARCHIVE_DOWNLOAD_ENABLED=false in the deployment’s configuration will set the RDM_ARCHIVE_DOWNLOAD_ENABLED setting to False, without needing to change invenio.cfg.

This is not applied automatically - call it explicitly from invenio.cfg, typically as the very last step, so that these overrides win over anything set by the configure_*() functions above it.

Parameters:

env (dict[str, Any] | None) – Normally left unset, in which case the values loaded from variables/.env/the process environment are used.

oarepo_config.communities

Configuration for communities.

class oarepo_config.communities.DefaultCommunitiesPermissionPolicy(action, **over)[source]

Bases: BooleanPermissionPolicyMixin, CommunityPermissionPolicy

Default permission policy for communities.

can_create = (<invenio_administration.generators.Administration object>, <invenio_records_permissions.generators.SystemProcess object>)
can_submit_record = (<oarepo_communities.services.permissions.generators.CanSubmitRecordInCommunity object>, <invenio_records_permissions.generators.SystemProcess object>)
can_include_directly = (<invenio_records_permissions.generators.SystemProcess object>,)
can_members_add = (<invenio_records_permissions.generators.SystemProcess object>,)
can_members_search_public = (<oarepo_communities.services.permissions.generators.DefaultCommunityRole object>, <oarepo_communities.services.permissions.generators.DefaultCommunityRole object>, <invenio_records_permissions.generators.SystemProcess object>)
can_members_update = (<invenio_communities.generators.CommunityManagersForRole object>, <invenio_records_permissions.generators.SystemProcess object>)
can_members_delete = (<invenio_communities.generators.CommunityManagersForRole object>, <invenio_records_permissions.generators.SystemProcess object>)
can_request_membership = (<invenio_records_permissions.generators.Disable object>,)
oarepo_config.communities.configure_communities(communities_roles=None)[source]

Set up the configuration for communities.

Communities let you organize records into collections with their own managers and settings. This function configures who can do what in each community (the roles), how records are submitted to communities, and other community-related settings.

Parameters:

communities_roles (list | None) – Custom role definitions for communities. If not provided, defaults to owner/curator/member roles. If omitted, three default roles are used: “owner” (can manage the community and its members), “curator” (can review/curate submitted records) and “member” (can only view). Pass your own list to replace the defaults, e.g. to add a “submitter” role. Each role dictionary understands the keys name, title, description, is_owner, can_manage, can_curate and can_manage_roles (the names of the roles this role is allowed to add/remove).

Invenio configuration variables set:

  • COMMUNITIES_REGISTER_UI_BLUEPRINT - always True; enables the communities UI.

  • COMMUNITIES_PERMISSION_POLICY - the permission policy class for communities.

  • COMMUNITIES_ROLES - the list of available roles in communities.

Example:

config.configure_communities()
# or with custom settings:

config.configure_communities(
    communities_roles=[
        dict(
            name="owner",
            title=_("Community owner"),
            is_owner=True,
            can_manage=True,
            can_manage_roles=[
                "owner",
                "curator",
                "member",
                "submitter",
            ],
        ),
        dict(
            name="curator",
            title=_("Curator"),
            can_manage=True,
            can_manage_roles=[
                "member",
                "submitter",
            ],
        ),
        dict(
            name="submitter",
            title=_("Submitter"),
            can_manage=True,
        ),
        dict(
            name="member",
            title=_("Member"),
        ),
    ]
)

oarepo_config.cron

Configuration for periodic (scheduled) background tasks.

oarepo_config.cron.configure_cron(**extra_cron_items)[source]

Set up the periodic (scheduled) background tasks the repository needs.

The repository relies on a number of jobs that must run automatically in the background on a regular basis - for example, cleaning up old sessions, aggregating usage statistics, or clearing caches. This function sets up a sensible set of such jobs out of the box:

  • keeping the search index queues healthy (every 10 seconds)

  • cleaning up expired user sessions and old IP address logs

  • processing and aggregating usage statistics (hourly)

  • clearing the communities cache (daily)

  • removing expired file-access-request tokens (daily)

Parameters:

**extra_cron_items (Any) –

Additional scheduled jobs to add (or to override, if the name matches one of the built-in jobs above), one keyword per job. Each value follows Celery’s “beat schedule” format, e.g.:

config.configure_cron(
    my_job={
        "task": "my_package.tasks.my_task",
        "schedule": timedelta(
            minutes=30
        ),
    },
)

Invenio configuration variables set:

  • CELERY_BEAT_SCHEDULE - merged with any schedule already defined earlier in invenio.cfg; entries from **extra_cron_items win over the built-in defaults listed above when their names collide.

oarepo_config.datastreams

Configuration for datastreams.

oarepo_config.datastreams.configure_datastreams(readers=None, writers=None, transformers=None)[source]

Register custom sources for importing vocabularies (fixtures) into the repository.

Vocabularies (controlled lists such as languages, resource types or licenses) can be loaded from files or external services using “datastreams” - a reader that fetches/reads the raw data, an optional transformer that converts it, and a writer that stores it. Invenio already ships with a set of built-in readers/writers/ transformers; use this function only if you need to add your own (for example, a reader that pulls a vocabulary from a custom REST API).

Parameters:

  • readers (dict[str, Any] | None) – Extra readers to make available, as a mapping of a short name to either an import path string ("my_package.readers:MyReader") or the class/object itself.

  • writers (dict[str, Any] | None) – Extra writers to make available, in the same format as readers.

  • transformers (dict[str, Any] | None) – Extra transformers to make available, in the same format as readers.

Any readers/writers/transformers already registered (for example by configure_generic_parameters()) are kept; the ones passed here are added on top.

Invenio configuration variables set:

  • VOCABULARIES_DATASTREAM_READERS - only if readers is given; merged with any existing value.

  • VOCABULARIES_DATASTREAM_WRITERS - only if writers is given; merged with any existing value.

  • VOCABULARIES_DATASTREAM_TRANSFORMERS - only if transformers is given; merged with any existing value.

Example:

config.configure_datastreams(
    readers={
        "myreader": "my_package:MyReader"
    },
    writers={
        "mywriter": "my_package:MyWriter"
    },
)

oarepo_config.einfra

Configuration for oarepo-oidc-einfra module.

oarepo_config.einfra.configure_einfra_oidc()[source]

Set up “Log in with e-INFRA” (CESNET/Perun) for the repository.

This enables single sign-on through the CESNET e-INFRA identity provider, so users can log in with their e-INFRA/Perun account instead of (or in addition to) a local username and password. It also makes user profile information (name, e-mail, …) read-only locally, since it is then managed by e-INFRA instead.

Requires the optional oarepo-oidc-einfra package to be installed - if it is missing, this function prints a message and stops the application from starting.

Whether e-INFRA login is actually turned on is controlled by the INVENIO_REMOTE_AUTH_ENABLED setting (true/yes/1 to enable it, anything else - including leaving it unset - disables it). When enabled, the client credentials INVENIO_EINFRA_CONSUMER_KEY and INVENIO_EINFRA_CONSUMER_SECRET must also be provided (see the deployment’s variables/.env configuration).

Invenio configuration variables set:

  • OAUTHCLIENT_REMOTE_APPS - always updated (merged with any existing value); gets an "e-infra" entry only when e-INFRA login is enabled.

  • EINFRA - only when e-INFRA login is enabled; the e-INFRA client credentials and endpoint configuration.

  • USERPROFILES_READ_ONLY - only when e-INFRA login is enabled; forced to True.

Example:

config.configure_einfra_oidc()

Make sure to set INVENIO_REMOTE_AUTH_ENABLED=true and provide INVENIO_EINFRA_CONSUMER_KEY and INVENIO_EINFRA_CONSUMER_SECRET in your deployment’s variables or environment.

oarepo_config.generic_parameters

Generic configuration parameters for oarepo-config.

oarepo_config.generic_parameters.configure_global_logging()[source]

Configure global logging settings.

oarepo_config.generic_parameters.configure_generic_parameters(languages=(('en', 'English'),), use_path_pid_ids=False)[source]

Set up the core, infrastructure-level configuration of the repository.

This is the main “plumbing” function that should normally be called first, before any of the other configure_* functions. It reads most of its values from the deployment’s environment configuration (the variables/.env files or process environment variables, all prefixed with INVENIO_) and uses them to configure:

  • the site’s public URLs, and allowed security headers

  • whether local login/registration/password-reset is available

  • the database, search engine (OpenSearch), file storage (S3), cache and message queue (Redis/RabbitMQ) connections

  • translation/locale and file-upload defaults

  • default identifier schemes recognised for names, funders and affiliations (e.g. ORCID, ROR, VEDIDK, Scopus author ID)

Because most values come from the environment, this function will fail to start the application if a required INVENIO_... variable is missing from the deployment’s configuration - see the project’s README for the full list of variables it expects.

Parameters:

  • languages (tuple[tuple[str, str], ...]) – Extra UI languages to offer, as a tuple of (language_code, label) pairs, e.g. (("cs", _("Czech")), ("de", _("German"))). English is always available and does not need to be listed.

  • use_path_pid_ids (bool) – Set this to True only if your repository uses record identifiers that themselves contain a slash (/); it adjusts the URLs used for managing record access so that such identifiers keep working.

Invenio configuration variables set, grouped by area:

Public URLs & security headers

  • APP_ALLOWED_HOSTS

  • SITE_UI_URL, SITE_API_URL

  • APP_DEFAULT_SECURE_HEADERS

Local login & accounts

  • ACCOUNTS_LOCAL_LOGIN_ENABLED, SECURITY_REGISTERABLE, SECURITY_RECOVERABLE, SECURITY_CHANGEABLE, SECURITY_CONFIRMABLE, SECURITY_LOGIN_WITHOUT_CONFIRMATION

  • SESSION_COOKIE_SECURE

  • RATELIMIT_GUEST_USER, RATELIMIT_AUTHENTICATED_USER

  • OAUTHCLIENT_REMOTE_APPS - starts out empty here; extended by configure_einfra_oidc() if used.

  • ACCOUNTS_LOGIN_VIEW_FUNCTION, OAUTHCLIENT_AUTO_REDIRECT_TO_EXTERNAL_LOGIN

Database

  • SQLALCHEMY_DATABASE_URI

Translation/locale

  • BABEL_DEFAULT_LOCALE, BABEL_DEFAULT_TIMEZONE, I18N_LANGUAGES

Files & storage

  • SEND_FILE_MAX_AGE_DEFAULT, FILES_REST_STORAGE_FACTORY

  • S3_ENDPOINT_URL, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY

  • FILES_REST_STORAGE_CLASS_LIST, FILES_REST_DEFAULT_STORAGE_CLASS, FILES_REST_DEFAULT_QUOTA_SIZE

  • APP_RDM_DEPOSIT_FORM_QUOTA

User profiles

  • USERPROFILES_READ_ONLY

OAI-PMH

  • OAISERVER_ID_PREFIX

Search (OpenSearch)

  • SEARCH_INDEX_PREFIX, SEARCH_HOSTS, SEARCH_CLIENT_CONFIG

  • VOCABULARIES_SERVICE_CONFIG, VOCABULARIES_RESOURCE_CONFIG - only if the optional oarepo_vocabularies package is installed.

Caches (Redis)

  • INVENIO_CACHE_TYPE, CACHE_REDIS_URL, ACCOUNTS_SESSION_REDIS_URL, COMMUNITIES_IDENTITIES_CACHE_REDIS_URL

Background jobs (Celery/RabbitMQ)

  • CELERY_BROKER_URL, BROKER_URL, CELERY_RESULT_BACKEND

JSON schemas

  • RECORDS_REFRESOLVER_CLS, RECORDS_REFRESOLVER_STORE, JSONSCHEMAS_HOST

Secrets

  • SECRET_KEY

Records/REST compatibility

  • DASHBOARD_RECORD_CREATE_URL, RECORD_ROUTES, RECORDS_REST_ENDPOINTS

DataCite/DOIs

  • DATACITE_TEST_MODE

Mail

  • MAIL_DEFAULT_SENDER

  • MAIL_SUPPRESS_SEND - only if INVENIO_MAIL_SUPPRESS_SEND is set in the environment.

Identifier/name/funder/affiliation vocabularies

  • VOCABULARIES_NAMES_SCHEMES, VOCABULARIES_FUNDER_SCHEMES, VOCABULARIES_AFFILIATION_SCHEMES - merged with any existing value.

  • APP_RDM_IDENTIFIER_SCHEMES_UI

  • VOCABULARIES_DATASTREAM_READERS, VOCABULARIES_DATASTREAM_WRITERS, VOCABULARIES_DATASTREAM_TRANSFORMERS - seeded from invenio-app-rdm’s defaults, merged with any existing value; see configure_datastreams() to add your own.

Miscellaneous

  • ROR_CLIENT_ID, SESSION_COOKIE_DOMAIN, COLLECT_STORAGE

In addition, if use_path_pid_ids is True, this patches the url_prefix of RDMParentRecordLinksResourceConfig, RDMParentGrantsResourceConfig, RDMGrantUserAccessResourceConfig and RDMGrantGroupAccessResourceConfig directly - this is a class attribute change, not a new invenio.cfg variable.

Example:

config.configure_generic_parameters(
    languages=(
        ("cs", _("Czech")),
        ("de", _("German")),
    ),
)

oarepo_config.i18n

Configuration for i18n.

oarepo_config.i18n.initialize_i18n()[source]

Enable translated validation error messages.

Makes sure that when a user submits invalid data (for example, a required field is missing), the error message shown to them is translated into their chosen language instead of always being shown in English. Takes no parameters; call it once, near the top of invenio.cfg.

Invenio configuration variables set: none - this only patches Marshmallow’s error-message machinery in memory.

Example:

config.initialize_i18n()

oarepo_config.initial_configuration

Plain module-level settings, not a configure_*() function - see the “initial_configuration.py / initial_rdm_config.py” section of the README for how (and whether) this currently gets loaded automatically.

Initial configuration module.

oarepo_config.initial_configuration.THEME_FRONTPAGE = False

Enable frontpage theme.

oarepo_config.initial_rdm_config

Plain module-level settings, not a configure_*() function - see the same note as above.

Initial configuration which replaces RDM service with oarepo extensions.

Please see oarepo/initial_rdm_config.py for explanation on how to handle the configuration.

oarepo_config.jobs

Configuration for the Jobs feature.

oarepo_config.jobs.configure_jobs(permission_policy=None, logging_level=None)[source]

Set up the “Jobs” feature (manually or automatically run administrative tasks).

Invenio-jobs lets administrators run and monitor maintenance tasks (such as re-indexing or fixing up data) from the admin panel, and view their logs. This decides who is allowed to view those job logs and how detailed the logs are.

Parameters:

  • permission_policy (str | type | None) – Who is allowed to view job logs. By default, only administrators can. Pass your own permission policy class (or its import path as a string) to change this.

  • logging_level (str | None) – How detailed the job logs should be, e.g. "DEBUG", "INFO" (the default), "WARNING".

Invenio configuration variables set:

  • APP_LOGS_PERMISSION_POLICY - the permission_policy above.

  • JOBS_LOGGING_LEVEL - the logging_level above.

Example:

config.configure_jobs()
# or with custom settings:
config.configure_jobs(
    permission_policy="my_package:policies:MyJobPolicy",
    logging_level="DEBUG",
)

oarepo_config.models

Configuration for models.

oarepo_config.models.add_model(model_package_name)[source]

Include a data model in the repository’s global (cross-model) search.

Repositories can host several different kinds of records (models), e.g. “datasets” and “publications”. Call this once per model package to make its records show up in searches that span all models at once (as opposed to searching within just one model). This does not register the model itself (its API endpoints, forms, etc.) - that is normally done separately, by calling that model package’s own register() function.

Parameters:

model_package_name (str) – The Python import path of the generated model package to add, e.g. "datasets" for a model built from a datasets model package. If the package cannot be found or has not been built yet, this is only logged as an error - it does not stop the repository from starting.

Invenio configuration variables set:

  • GLOBAL_SEARCH_MODELS - the model’s MODEL_DEFINITION is appended to this list; any models already registered (by earlier calls, or by other packages) are kept.

Example:

from datasets import datasets_model

datasets_model.register()
config.add_model("datasets")

oarepo_config.oai

Configuration for OAI-PMH.

oarepo_config.oai.configure_oai()[source]

Set up OAI-PMH, the protocol other systems use to harvest records from this repository.

OAI-PMH is a standard way for external services (e.g. national aggregators, other repositories) to regularly fetch a list of published records. This announces the repository’s name over that protocol, using the name already set via configure_ui().

Takes no parameters. Must be called after configure_ui(), since it needs the repository name that function sets up; calling it earlier raises an error explaining this.

Invenio configuration variables set:

  • OAISERVER_REPOSITORY_NAME - copied from REPOSITORY_NAME (set by configure_ui()).

Example:

config.configure_oai()

oarepo_config.stats

Configuration for invenio-stats module.

oarepo_config.stats.configure_stats(enable=True)[source]

Set up usage statistics (record views, downloads, etc.).

Enables the collection and aggregation of usage events, such as how many times a record was viewed or a file was downloaded, so this data can later be shown to users and curators.

Parameters:

enable (bool) – Set to False to turn off collecting new usage statistics events (for example on a staging/test instance). Defaults to True.

Invenio configuration variables set:

  • STATS_REGISTER_RECEIVERS - the enable argument above.

  • STATS_EVENTS, STATS_AGGREGATIONS, STATS_QUERIES, STATS_PERMISSION_FACTORY - always set to invenio-app-rdm’s defaults, regardless of enable.

Example:

config.configure_stats()
# or on a test instance:
config.configure_stats(enable=False)

oarepo_config.ui

Configuration for the repository UI.

oarepo_config.ui.configure_ui(code='myrepo', name='My Repository', subtitle='', description='', support_contact='', keywords='', use_default_frontpage=False, show_frontpage_intro=True, analytics=False, languages=(('en', 'English'),))[source]

Set up the repository’s branding, name and general look-and-feel.

Configures what visitors see: the repository’s name and description shown in the browser tab/search results/front page, the theme, the page layout templates, and (optionally) analytics tracking.

Parameters:

  • code (str) – A short, technical, all-lowercase identifier for this repository (e.g. "myrepo"); used internally to select the repository’s own theme files.

  • name (str | Any) – The repository’s display name, shown in the browser title and on the front page, e.g. _("My Repository").

  • subtitle (str) – A short subtitle/tagline shown next to the name.

  • description (str) – A longer description of the repository, used for SEO and on the front page.

  • support_contact (str) – Contact information (e.g. an e-mail address) shown to users who need help.

  • keywords (str) – Keywords describing the repository’s content, used for SEO.

  • use_default_frontpage (bool) – Whether to use Invenio’s generic front page. Most repositories provide a custom front page, so this defaults to False.

  • show_frontpage_intro (bool) – Whether to show the introductory text section on the front page.

  • analytics (str | bool) – Set to "matomo" to enable Matomo web analytics tracking (only takes effect on deployed, non-local instances; requires the Matomo URL/site ID to be configured in the deployment’s environment). False (the default) disables analytics.

  • languages (tuple[tuple[str, str], ...]) – Extra UI languages to offer, as a tuple of (language_code, label) pairs. English is always available and does not need to be listed. This should normally match what was passed to configure_generic_parameters().

Should be called after configure_generic_parameters() (it builds on settings that function prepares) and before configure_oai() (which needs the repository name set here).

Example:

config.configure_ui(
    code="myrepo",
    name=_("My Repository"),
    description=_(
        "A repository for my data"
    ),
    support_contact="support@example.com",
)

Invenio configuration variables set, grouped by area:

Versioning

  • DEPLOYMENT_VERSION

Theme & security

  • APP_THEME

  • APP_DEFAULT_SECURE_HEADERS - extends the value prepared by configure_generic_parameters().

Page layout templates

  • INSTANCE_THEME_FILE

  • BASE_TEMPLATE, ADMINISTRATION_THEME_BASE_TEMPLATE, COVER_TEMPLATE

  • THEME_CSS_TEMPLATE, THEME_JAVASCRIPT_TEMPLATE

  • HEADER_TEMPLATE, THEME_HEADER_TEMPLATE, THEME_HEADER_LOGIN_TEMPLATE, THEME_FOOTER_TEMPLATE

  • THEME_TRACKINGCODE_TEMPLATE, THEME_FRONTPAGE_TEMPLATE

  • SETTINGS_TEMPLATE, SEARCH_UI_SEARCH_TEMPLATE

Analytics

  • MATOMO_ANALYTICS_TEMPLATE, MATOMO_ANALYTICS_URL, MATOMO_ANALYTICS_SITE_ID - only if analytics="matomo" and this is not a local-development deployment.

Branding

  • THEME_FRONTPAGE, THEME_LOGO, THEME_FRONTPAGE_LOGO

  • THEME_SITENAME, THEME_FRONTPAGE_TITLE, THEME_SHOW_FRONTPAGE_INTRO_SECTION

Repository metadata (SEO & front page)

  • REPOSITORY_NAME, REPOSITORY_DESCRIPTION, REPOSITORY_SUPPORT_CONTACT, REPOSITORY_SUBTITLE, REPOSITORY_KEYWORDS

Build pipeline

  • JAVASCRIPT_PACKAGES_MANAGER, ASSETS_BUILDER, WEBPACKEXT_NPM_PKG_CLS, WEBPACKEXT_PROJECT

Records & deposit UI

  • RECORDS_UI_ENDPOINTS, APP_RDM_DEPOSIT_NG_FILES_UI_ENABLED, DASHBOARD_RECORD_CREATE_URL

  • APP_RDM_DETAIL_SIDE_BAR_TEMPLATES

Search UI

  • THEME_SEARCH_ENDPOINT, SEARCH_UI_SEARCH_VIEW

oarepo_config.vocabulary

Configuration for vocabulary.

oarepo_config.vocabulary.configure_vocabulary(code, **kwargs)[source]

Declare a custom controlled vocabulary (a fixed list of allowed values).

Vocabularies are controlled lists of values that records can pick from, such as languages, resource types or licenses. Call this once for each additional vocabulary type your repository needs, to describe it and any extra properties it should have.

Parameters:

  • code (str) – A short, unique identifier for the vocabulary, e.g. "languages".

  • **kwargs (Any) –

    Extra details describing the vocabulary, typically including name (its display name), description, and props (a description of any extra fields each entry in the vocabulary should have, and how they appear in forms). See the OARepo reference docs for the full list of supported keys.

Calling this multiple times with different code values adds multiple vocabularies; it does not replace previously configured ones.

Invenio configuration variables set:

  • INVENIO_VOCABULARY_TYPE_METADATA - the entry for code is set to kwargs; entries for other vocabulary codes (added by earlier calls) are kept.

Example:

config.configure_vocabulary(
    code="languages",
    name=_("Languages"),
    description=_(
        "Language definitions"
    ),
    props={
        "alpha3Code": {
            "description": _(
                "ISO 639-2 standard 3-letter language code"
            ),
            "multiple": False,
            "search": False,
        },
    },
    dump_options=True,
)

oarepo_config.workflows

register_workflow, configure_workflows, CommunityWorkflow, IndividualWorkflow and BaseWorkflowSettings are already documented above under the top-level package; :no-index: avoids re-registering those (Sphinx errors on class descriptions - unlike functions - being registered twice) while still showing them here too.

Configuration for workflows.

class oarepo_config.workflows.BaseWorkflowSettings(code='undefined', label=l'Undefined policy', base_permission_policy=<class 'oarepo_config.workflows.simplified.workflow_permissions.DefaultRDMWorkflowPermissions'>, base_request_policy=<class 'oarepo_workflows.requests.policy.WorkflowRequestPolicy'>, review_request_states=<factory>, record_view_permissions=<factory>, publish_after_review=True, extra_permissions=None, extra_requests=None, authenticated_draft_creation=False, draft_creation_roles=<factory>, draft_creation_needs=<factory>)[source]

Bases: object

Shared configuration common to all workflow types.

authenticated_draft_creation: bool = False

Allow authenticated users to create draft records.

When enabled and no role- or need-based restrictions are configured, any authenticated user may create a draft. Subclasses may override this default (e.g. IndividualWorkflow sets it to True).

base_permission_policy

alias of DefaultRDMWorkflowPermissions

base_request_policy

alias of WorkflowRequestPolicy

build_workflow()[source]

Build and return the workflow instance.

code: str = 'undefined'

The code of the workflow type.

extra_permissions: type[BasePermissionPolicy] | Callable[[type[BasePermissionPolicy]], type[BasePermissionPolicy]] | None = None

Extra permissions to apply to the record permission policy.

If a callable is provided, it will be called with the generated permission policy as an argument and should return a modified permission policy. If a class is provided, it will be used as a mixin for the generated permission policy.

extra_requests: type[WorkflowRequestPolicy] | Callable[[type[WorkflowRequestPolicy]], type[WorkflowRequestPolicy]] | None = None

Extra requests to apply to the workflow request policy.

If a callable is provided, it will be called with the generated request policy as an argument and should return a modified request policy. If a class is provided, it will be used as a mixin for the generated request policy.

label: LazyString = l'Undefined policy'

The label of the workflow type.

publish_after_review: bool = True

Publish immediately after reviewer approves the review request.

review_request_states: list[str]

Record workflow states in which a review request may be submitted.

record_view_permissions: dict[str, list[Generator]]

View permissions for records in this workflow.

It is a dictionary, the key is record state and the value is a list of generators.

draft_creation_roles: list[str]

Restrict draft creation to users who hold at least one of these site-wide roles.

When non-empty, takes priority over authenticated_draft_creation.

draft_creation_needs: list[str]

Restrict draft creation to users who hold at least one of these permission needs.

When non-empty, takes priority over authenticated_draft_creation.

class oarepo_config.workflows.CommunityWorkflow(code='undefined', label=l'Undefined policy', base_permission_policy=<class 'oarepo_config.workflows.simplified.workflow_permissions.DefaultRDMWorkflowPermissions'>, base_request_policy=<class 'oarepo_workflows.requests.policy.WorkflowRequestPolicy'>, review_request_states=<factory>, record_view_permissions=<factory>, publish_after_review=True, extra_permissions=None, extra_requests=None, authenticated_draft_creation=False, draft_creation_roles=<factory>, draft_creation_needs=<factory>, draft_creation_community_roles=<factory>, read_restricted_community_roles=<factory>, read_draft_community_roles=<factory>, record_manage_community_roles=<factory>, community_curator_roles=<factory>)[source]

Bases: BaseWorkflowSettings

Workflow configuration for deposits inside communities.

draft_creation_community_roles: list[str]

Restrict draft creation to community members with at least one of these roles.

If not specified (empty list), any member of the community can create a draft. Used in addition to the site-wide draft_creation_roles / draft_creation_needs restrictions.

read_restricted_community_roles: list[str]

Community roles that may read restricted (published) records without requesting access.

If empty, only the record owner can read the content after publishing. By default allowing curators and community owners to access restricted records.

Note

Community roles are used instead of RecordCommunitiesAction so that each workflow can have independent read/draft/manage permissions.

read_draft_community_roles: list[str]

Community roles that may read draft records without requesting access.

If empty, only the record owner can read the content of a draft. Curators can always read draft records when the record is submitted for review.

Note

Community roles are used instead of RecordCommunitiesAction so that each workflow can have independent read/draft/manage permissions.

record_manage_community_roles: list[str]

Community roles that may manage (edit, delete, publish) records.

If empty, only the record owner can manage the record. By default allowing curators and community owners to manage all records.

Note

Community roles are used instead of RecordCommunitiesAction so that each workflow can have independent read/draft/manage permissions.

community_curator_roles: list[str]

Community roles that allow users to review and curate records.

review_request_states: list[str]

Record workflow states in which a review request may be submitted.

record_view_permissions: dict[str, list[Generator]]

View permissions for records in this workflow.

It is a dictionary, the key is record state and the value is a list of generators.

draft_creation_roles: list[str]

Restrict draft creation to users who hold at least one of these site-wide roles.

When non-empty, takes priority over authenticated_draft_creation.

draft_creation_needs: list[str]

Restrict draft creation to users who hold at least one of these permission needs.

When non-empty, takes priority over authenticated_draft_creation.

class oarepo_config.workflows.IndividualWorkflow(code='individual', label=l'Individual Submission Workflow', base_permission_policy=<class 'oarepo_config.workflows.simplified.workflow_permissions.DefaultRDMWorkflowPermissions'>, base_request_policy=<class 'oarepo_workflows.requests.policy.WorkflowRequestPolicy'>, review_request_states=<factory>, record_view_permissions=<factory>, publish_after_review=True, extra_permissions=None, extra_requests=None, authenticated_draft_creation=True, draft_creation_roles=<factory>, draft_creation_needs=<factory>, publish_without_review=False, publish_without_review_roles=<factory>, publish_without_review_needs=<factory>, publish_without_review_states=<factory>, review_required=False, reviewer_roles=<factory>, reviewer_needs=<factory>, self_review_enabled=False)[source]

Bases: BaseWorkflowSettings

Workflow configuration for deposits outside of communities.

authenticated_draft_creation: bool = True

Allow authenticated users to create drafts in this workflow.

Overrides the base-class default of False; any authenticated user can create a draft unless more-specific role or need restrictions are configured via draft_creation_roles or draft_creation_needs.

code: str = 'individual'

Unique code identifier for this workflow.

label: LazyString = l'Individual Submission Workflow'

Human-readable label for this workflow.

publish_without_review: bool = False

Allow draft owners to publish without submitting a review request.

When enabled, draft owners can publish directly, subject to publish_without_review_states.

record_owners_with_correct_roles(record_owner_generator)[source]

Return the record owner generator with the correct roles/needs.

review_required: bool = False

Require a review request before publication.

If publish_without_review is False and review_required is False, records can only be published through a community workflow.

self_review_enabled: bool = False

Allow the record owner to approve their own review request.

Normally, submitting a record for review prevents the owner from approving it themselves. When set to True, the review request is still created on submission, but the owner is permitted to accept it.

This is primarily useful when invenio-checks is active: checks are tied to an open request, so the request must exist even when no external reviewer is needed. With this option the owner can see and act on the check results without waiting for a curator.

Has no effect when publish_without_review is True, because in that case user can bypass the review request and publish the record directly.

publish_without_review_roles: list[str]

Roles that allow a draft owner to publish without a review request.

Users must still be owners of the draft record. If the list is non-empty, publish_without_review is ignored.

publish_without_review_needs: list[str]

Permission needs that allow a draft owner to publish without a review request.

Users must still be owners of the draft record. If the list is non-empty, publish_without_review is ignored.

publish_without_review_states: list[str]

Record workflow states in which publication without review is allowed.

reviewer_roles: list[str]

Roles that allow users to review and curate records.

Users with these roles are also granted read access to draft records.

reviewer_needs: list[str]

Permission needs that allow users to review and curate records.

Users with these needs are also granted read access to draft records.

review_request_states: list[str]

Record workflow states in which a review request may be submitted.

record_view_permissions: dict[str, list[Generator]]

View permissions for records in this workflow.

It is a dictionary, the key is record state and the value is a list of generators.

draft_creation_roles: list[str]

Restrict draft creation to users who hold at least one of these site-wide roles.

When non-empty, takes priority over authenticated_draft_creation.

draft_creation_needs: list[str]

Restrict draft creation to users who hold at least one of these permission needs.

When non-empty, takes priority over authenticated_draft_creation.

oarepo_config.workflows.configure_workflows(*workflow_definitions, default_individual_workflow='individual', default_community_workflow='community', context=None)[source]

Set up workflows based on the provided workflow definitions.

This function is intended to be called from within invenio.cfg and will create a “WORKFLOWS” entry in the invenio.cfg context (in the caller’s globals).

Example

# invenio.cfg
from oarepo_app.config import (
    configure_workflows,
    IndividualWorkflow,
    CommunityWorkflow,
)

configure_workflows(
    IndividualWorkflow(
        authenticated_draft_creation=False,
        review_required=True,
        publish_without_review=False,
    ),
    CommunityWorkflow(),
)
# no need to assign the result to WORKFLOWS, that is done automatically

If the workflow definitions are empty, a permissive IndividualWorkflow will be created (authenticated draft creation, publish without review allowed).

If there is no IndividualWorkflow definition in the workflow definitions (but there are other workflow types), a restricted IndividualWorkflow (no deposition allowed) will be created with default settings.

The default_individual_workflow parameter should be the code of the workflow to use as the default one for individual deposits, where no community is involved and the workflow code is not provided by the caller.

If the context is provided, the “WORKFLOWS” entry will be added to it instead of the caller’s globals.

See https://nrp-cz.github.io/docs/customize/workflows for more information on how to customize the workflows.

oarepo_config.workflows.register_workflow(workflow_code, workflow_name, permissions_policy, requests_policy, use_low_level_workflows=False)[source]

Register a submission/review workflow that records can go through.

A workflow defines the path a record takes from being created to being published - for example, who may create it, whether it needs review/approval before publishing, and who may perform each of those steps. This adds one such workflow to the repository, so that it can be selected when configuring where records may be submitted (e.g. a community).

This is a low-level, single-workflow building block. Repositories that use the community-based workflow shape provided by the oarepo_app package typically use its higher-level configure_workflows(IndividualWorkflow(...), CommunityWorkflow(...)) helper instead - see this package’s README for the difference.

Parameters:

  • workflow_code (str) – A short, unique identifier for the workflow, e.g. "default".

  • workflow_name (str | Any) – The human-readable name of the workflow, shown to users, e.g. _("Default workflow").

  • permissions_policy (str | type) – Who is allowed to do what with records that use this workflow (create, edit, delete, publish, …). Pass either a permissions policy class or its import path as a string.

  • requests_policy (str | type) – What review/approval requests are available for records using this workflow (e.g. a publish request that needs a curator’s approval). Pass either a request policy class or its import path as a string.

  • use_low_level_workflows (bool) – Set to True to silence the warning recommending configure_workflows() instead, for the (uncommon) cases that genuinely need this low-level, single-workflow API.

Requires the optional oarepo_workflows (and, for its defaults, oarepo_requests) package to be installed.

Invenio configuration variables set:

  • WORKFLOWS - the new workflow is appended; workflows already registered (by earlier calls) are kept.

  • REQUESTS_PERMISSION_POLICY - only if not already set by an earlier call; defaults to CreatorsFromWorkflowRequestsPermissionPolicy.

Example:

from oarepo_workflows.services.permissions import (
    DefaultWorkflowPermissions,
)
from oarepo_requests.services.permissions.workflow_policies import (
    CreatorsFromWorkflowRequestsPermissionPolicy,
)

config.register_workflow(
    workflow_code="default",
    workflow_name=_("Default workflow"),
    permissions_policy=DefaultWorkflowPermissions,
    requests_policy=CreatorsFromWorkflowRequestsPermissionPolicy,
)