Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

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: about 2 months ago
JSON representation

FlowCore is a Rails engine to help you build your automation or business process application.

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:



![Architecture](guides/assets/architecture.en.svg)



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



![Life cycle of workflow instance](guides/assets/instance_lifecycle.en.svg)



### 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).