Skip to content

Latest commit

 

History

History
235 lines (152 loc) · 6.76 KB

README.md

File metadata and controls

235 lines (152 loc) · 6.76 KB
Raw

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:

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

Life cycle of workflow instance

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

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

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.