OArepo FSM library for record state transitions
Project description
OArepo FSM library for record state transitions built on top of the https://pypi.org/project/sqlalchemy-fsm/ library.
Quickstart
Run the following commands to bootstrap your environment
git clone https://github.com/oarepo/oarepo-fsm cd oarepo-fsm pip install -e .[devel]
Configuration
Check that correct record_class is being used on the RECORDS_REST_ENDPOINT’s item_route
item_route='/records/<pid(recid,record_class="yourapp.models:RecordModelFSM"):pid_value>',
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
links_factory_imp='oarepo_fsm.links:record_fsm_links_factory',
If you wish to activate FSM on a certain Record enpoints only, put in your config
OAREPO_FSM_ENABLED_REST_ENDPOINTS = ['recid']
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.
Usage
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.
@transition( src=['open', 'archived'], dest='published', required=['id'], permissions=[editor_permission], commit_record=True) 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.
REST API Usage
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 https://oarepo-fsm.readthedocs.io/
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 RECORDS_REST_ENDPOINTS = dict( recid=dict( create_permission_factory_imp=deny_all, delete_permission_factory_imp=deny_all, update_permission_factory_imp=deny_all, read_permission_factory_imp=allow_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
require_all( states_required('editing'), editing_user_permission_factory )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
require_any( require_all( states_required('editing'), editing_user_permission_factory ), require_all( states_required('editing', 'approving), curator_user_permission_factory ), )
Changes
Version 0.1.0 (released TBD)
Initial public release.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for oarepo_fsm-2.0.2-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | dfba3ad011e4febe6c193628f9d9fda9582925206c3c5eb8af485c3feda0124d |
|
MD5 | e9a55d9f7ea3f44e13d60a3916dcc729 |
|
BLAKE2b-256 | b18f158c4e698837f658cf708248088ba80ec6b093a08db50ad29773bac17ba1 |