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 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 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

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.