Flow Core

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

Description

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

FlowCore is not an out-of-box gem, it's only provide essentials of workflow engine:

- Workflow definitions persist in database - Workflow modeling - PetriNet for low level presentation and scheduling, a special form Directed acyclic graph, can tracking concurrent states and express complex business process. - Pipeline, original, flowchart-based aim to human readable and correctness workflow modeling - Interfaces and abstract models for integration

You may consider FlowCore if you:

- Working on BPM, OA or similiar application - User-defined workflow and have concurrent tasks running on one instance

Monthly Downloads: 72

Programming language: Ruby

License: MIT License

Tags: Automation     Rails Engine     Workflow     Workflow Engine    

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

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

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

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