https://github.com/rails-engine/flow_core
FlowCore is a Rails engine to help you build your automation or business process application.
https://github.com/rails-engine/flow_core
automation bpm business-process petri-net rails-engine ruby ruby-on-rails workflow-engine
Last synced: 8 months ago
JSON representation
FlowCore is a Rails engine to help you build your automation or business process application.
- Host: GitHub
- URL: https://github.com/rails-engine/flow_core
- Owner: rails-engine
- License: mit
- Created: 2020-02-17T20:04:51.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2024-09-27T08:02:02.000Z (about 1 year ago)
- Last Synced: 2025-03-30T06:06:44.631Z (9 months ago)
- Topics: automation, bpm, business-process, petri-net, rails-engine, ruby, ruby-on-rails, workflow-engine
- Language: Ruby
- Homepage:
- Size: 906 KB
- Stars: 179
- Watchers: 5
- Forks: 22
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- License: MIT-LICENSE
Awesome Lists containing this project
README
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.
[中文介绍](README.zh-CN.md)
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](https://guides.rubyonrails.org/engines.html#improving-engine-functionality) suggests.
Your app-specific workflow triggers, and guards can be extended via [Single Table Inheritance](https://guides.rubyonrails.org/association_basics.html#single-table-inheritance)
FlowCore also provides callbacks for triggers (which control behavior of a transition) covered whole task lifecycle.
### Petri-net based
[Petri-net](https://en.wikipedia.org/wiki/Petri_net) is a technique for description and analysis of concurrent systems.
FlowCore choose its special type called [Workflow-net](http://mlwiki.org/index.php/Workflow_Nets) 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](http://workflowpatterns.com) 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](http://mlwiki.org/index.php/Workflow_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.
```sh
$ git clone https://github.com/rails-engine/flow_core.git
```
Change directory
```sh
$ cd flow_core
```
Run bundler
```sh
$ bundle install
```
Preparing database
```sh
$ bin/rails db:migrate
```
Import sample workflow
```sh
$ bin/rails db:seed
```
Build Script Core
```sh
$ bin/rails app:script_core:engine:build
$ bin/rails app:script_core:engine:compile_lib
```
Start the Rails server
```sh
$ 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](https://www.tonymarston.net/php-mysql/workflow.html).
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 Token
- `enabled` 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`
- `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 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:
```ruby
gem "flow_core"
```
Or you may want to include the gem directly from GitHub:
```ruby
gem 'flow_core', github: 'rails-engine/flow_core'
```
And then execute:
```bash
$ bundle
```
And then execute:
```bash
$ rails flow_core_engine:install:migrations
```
And then execute:
```bash
$ rails db:migrate
```
## References
- [hooopo/petri_flow](https://github.com/hooopo/petri_flow) (my partner's version, we share the same basis)
-
-
-
## Contributing
Bug report or pull request are welcome.
### Make a pull request
1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. 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](https://opensource.org/licenses/MIT).