Skip to main content

OArepo FSM library for record state transitions

Project description

OArepo FSM library for record state transitions built on top of the library.


Run the following commands to bootstrap your environment

git clone
cd oarepo-fsm
pip install -e .[devel]


Check that correct record_class is being used on the RECORDS_REST_ENDPOINT’s item_route


To automatically add a link to the FSM endpoint to your record links, use the following links_factory_imp in your RECORDS_REST_ENDPOINTS config


If you wish to activate FSM on a certain Record enpoints only, put in your config


Where recid is the prefix key into your RECORDS_REST_ENDPOINTS configuration. This library activates FSM on all endpoints using record_class inherited from FSMMixin otherwise.


In order to use this library, you need to define a Record model in your app, that inherits from a FSMMixin column

from invenio_records import Record
from oarepo_fsm.mixins import FSMMixin

class RecordModelFSM(FSMMixin, Record):

To define FSM transitions on this class, create methods decorated with @transition(..) e.g.

    src=['open', 'archived'],
def publish(self, **kwargs):
    print('record published')

Where decorator parameters mean:

  • src: record must be in one of the source states before transition could happen

  • dest: target state of the transition

  • required: a list of required **kwargs that must be passed to the @transition decorated function

  • permissions: currently logged user must have at least one of the permissions to execute the transition

  • commit_record: should the changes made in a record be commited after the function returns?

A transition-decorated function can optionally return a custom flask Response or a JSON-serializable dict to be provided to user in a JSON response.

“state” field name

To change state field name, set

class MyRecord(FSMMixin, ...):
    STATE_FIELD = 'administrative_props.state'

Note that the field name might be nested. If the container element does not exist, it will be created on the first transition.

Note: if you use your own state field, do not use marshamllow mixin, json schema or included mappings. Write/use your own.


To get current record state and possible transitions (only transitions that you have permission to invoke will be returned)

GET <record_rest_item_endpoint>
    metadata: {
        state: <current state of the record>
        ... other record metadata
    links: {
        self: ...,
        "transitions": {
            <fsm_transition1_name>: <transition_url>,
            <fsm_transition2_name>: <transition_url>,

To invoke a specific transition transition, do

POST <record_rest_endpoint>/<fsm_transition_name>

Further documentation is available on

Permission factories

Sometimes access to records should be governed by the state of the record. For example, if the record is in state=editing, any editor can make changes. If it is state=approving, only the curator can modify the record.

On REST level, modification permissions are governed by permission factories

from invenio_records_rest.utils import allow_all, deny_all

This library provides the following factories and helpers:

  • transition_required(*transitions) allows user if he is entitled to perform any of the transitions ( method names) on the current record

  • states_required(*states, state_field="state" allows anyone if the record is in any of the states mentioned

  • require_all(*perms_or_factories) allows user only if all permissions allow. Use it with states_required as follows


    where editing_user_permission_factory is a permission factory allowing only editing users.

  • require_any(*perms_or_factories) allows user if any of the permissions allow. Example

            states_required('editing', 'approving),


Version 0.1.0 (released TBD)

  • Initial public release.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

oarepo-fsm-2.0.4.tar.gz (20.3 kB view hashes)

Uploaded source

Built Distribution

oarepo_fsm-2.0.4-py2.py3-none-any.whl (18.6 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page