Flow Core
FlowCore is ready for open reviewing, but it haven't tested in production yet, any help are most welcome, breaking change is acceptable.
FlowCore is a Rails engine to help you build your automation or business process application.
FlowCore modeling workflow with WorkflowNet (a special case of PetriNet) theory which is a generalisation of automata theory such that the concept of concurrently occurring events can be expressed.
You should try FlowCore if you need:
- Working on BPM, OA, CRM or other similar products
- Working on Airflow-or-n8n-like automation product
- Embeds in your Rails app, interact your codebase directly
- User defined workflow
- Jobs have dependent relationships, may running in different stages
Features
Support all databases which based on ActiveRecord
All persistent data are present as ActiveRecord model and not use any DB-specific feature.
Easy to extend & hack
FlowCore basically followed best practice of Rails engine, you can extend as Rails Guides suggests.
Your app-specific workflow triggers, and guards can be extended via Single Table Inheritance
FlowCore also provides callbacks for triggers (which control behavior of a transition) covered whole task lifecycle.
Petri-net based
Petri-net is a technique for description and analysis of concurrent systems.
FlowCore choose its special type called Workflow-net to expressing workflow.
Compared to more popular activity-based workflow definitions (e.g BPMN), Petri-net has only few rules but could express very complex case.
Check workflow patterns to learn how to use Petri-net expressing workflows.
Basic workflow checking.
A workflow should be verified first before running it.
FlowCore provides the mechanism to help to prevent unexpected error on instance running
This is the hard work and help wanted Workflow-net has soundness checking but I don't know how to implement it
Interfaces and abstractions to integrate your business
FlowCore separate app-world and engine-world using interfaces and abstract classes, basically you no need to know Workflow-net internal works.
Runtime error and suspend support
FlowCore provides necessary columns and event callbacks for runtime error and suspend.
A DSL to simplify workflow creation
FlowCore provides a powerful DSL for creating workflow.
Demo
You need to install Graphviz first
Clone the repository.
$ git clone https://github.com/rails-engine/flow_core.git
Change directory
$ cd flow_core
Run bundler
$ bundle install
Preparing database
$ bin/rails db:migrate
Import sample workflow
$ bin/rails db:seed
Build Script Core
$ bin/rails app:script_core:engine:build
$ bin/rails app:script_core:engine:compile_lib
Start the Rails server
$ bin/rails s
Open your browser, and visit http://localhost:3000
Design
Architecture:
Basic design based on An activity based Workflow Engine for PHP By Tony Marston.
Some notable:
- Arc: The line to connecting a Place and a Transition
- ArcGuard: The matcher to decide the arc is passable, it's an base class that you can extend it for your own purpose.
- Task: A stateful record to present current workflow instance work,
and can reference a
TaskExecutable
through Rails polymorphic-reference. It finish means the transition is done and can moving on. - TaskExecutable: An interface for binding App task and FlowCore Task.
- TransitionTrigger: It controls the behavior of a Transition, it's an base class that you can extend it for your own purpose, best place for implementing business.
Lifecycle of Task
created
Task created by a Petri-net Tokenenabled
Transit to this stage when next transition requirement fulfilled- Best chance to create app task (your custom task for business) in
TransitionTrigger#on_task_enabled
- Best chance to create app task (your custom task for business) in
finished
Normal ending- Require app task finished first (if bind)
terminated
Task killed by instance (e.g Instance cancelled) or other race condition task
Why "core"
Because it's not aim to "out-of-box", some gem like Devise giving developer an out-of-box experience, that's awesome, but on the other hand, it also introducing a very complex abstraction that may hard to understanding how it works, especially when you attempting to customize it.
I believe that the gem is tightly coupled with features that face to end users directly, so having a good customizability and easy to understanding are of the most concern, so I just wanna give you a domain framework that you can build your own that just fitting your need, and you shall have fully control and without any unnecessary abstraction.
TODO / Help wanted
- Document
- Test
- Activity-based to Petri-net mapping that will possible to integrate to existing visual editors (with some modification), see https://www.researchgate.net/figure/The-mapping-between-BPMN-and-Petri-nets_tbl2_221250389 for understanding.
- More efficient and powerful workflow definition checking
- Grammar and naming correction (I'm not English native-speaker)
Usage
WIP
Requirement
- Rails 6.0+
- Ruby 2.5+
Installation
Add this line to your application's Gemfile:
gem "flow_core"
Or you may want to include the gem directly from GitHub:
gem 'flow_core', github: 'rails-engine/flow_core'
And then execute:
$ bundle
And then execute:
$ rails flow_core_engine:install:migrations
And then execute:
$ rails db:migrate
References
- hooopo/petri_flow (my partner's version, we share the same basis)
- http://mlwiki.org/index.php/Petri_Nets
- https://www.tonymarston.net/php-mysql/workflow.html
- http://workflowpatterns.com/
Contributing
Bug report or pull request are welcome.
Make a pull request
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request
Please write unit test with your code if necessary.
License
The gem is available as open source under the terms of the MIT License.