Spot Flow is a workflow engine for Rails applications based on the bpmn standard. It executes business processes defined in a modeler. It uses Spot Feel to evaluate expressions and business rules in the BPMN model. It can be used with Spot Form to render dynamic forms for user tasks.
The engine executes business processes like this one.
Processes are made of a series of tasks. Tasks can be manual (require signal
to be called) or automated (can be run
by the engine). The engine supports the following task types:
- Task and UserTask (manual): requires a signal to continue.
- ServiceTask (automated): instantiates a type defined in the task definition and invokes
call
on it. - BusinessRuleTask (automated): evaluates the decision_id (expects dmn source to be included in the context).
- ScriptTask (automated): evaluates the FEEL expression in the script property.
To start the process, initialize SpotFlow with the BPMN and DMN source files, then call start
.
sources = [
File.read("hello_world.bpmn"),
File.read("choose_greeting.dmn")
]
execution = SpotFlow.new(sources).start
It's often useful to print the process state to the console.
execution.print
HelloWorld started * Flow_080794y
0 StartEvent Start: completed * out: Flow_080794y
1 UserTask IntroduceYourself: waiting * in: Flow_080794y
2 BoundaryEvent EggTimer: waiting
The HelloWorld process began at the Start event and is waiting at the IntroduceYourself user task. This is an important concept in the SpotFlow engine. It's designed to be used in a Rails application where a process might be waiting for a user to complete a form, or a background job to complete. It's common to save the state the process until a task is complete. Calling serialize
on a process will return the execution state so it can be continued later.
# Returns a hash of the process state.
execution_state = execution.serialize
# Now we can save the execution state in a database until a user submits a form (UserTask)
# or a background job completes (ServiceTask)
# Restores the process from the execution state.
execution = SpotFlow.restore(sources, execution_state:)
# Now we can continue the process by `signaling` the waiting task.
step = execution.step_by_element_id("IntroduceYourself")
step.signal(name: "Eric", language: "it", formal: false, cookie: true)
After the IntroduceYourself task is signaled, the execution continues.
HelloWorld started * Flow_0gi9kt6, Flow_0pb7kh6
{
"name": "Eric",
"language": "it",
"formal": false,
"cookie": true
}
0 StartEvent Start: completed * out: Flow_080794y
1 UserTask IntroduceYourself: completed { "name": "Eric", "language": "it", "formal": false, "cookie": true } * in: Flow_080794y * out: Flow_0t9jhga
2 BoundaryEvent EggTimer: terminated
3 ParallelGateway Split: completed * in: Flow_0t9jhga * out: Flow_0gi9kt6, Flow_0q1vtg3
4 BusinessRuleTask ChooseGreeting: waiting * in: Flow_0gi9kt6
5 ExclusiveGateway WantsCookie: completed * in: Flow_0q1vtg3 * out: Flow_0pb7kh6
6 ServiceTask ChooseFortune: waiting * in: Flow_0pb7kh6
When execution reaches the Split inclusive gateway, it forks into two paths. The first path is waiting at the ChooseGreeting business rule task. The second reaches the WantsCookie exclusive gateway and evaluates the sequence flow conditions before continuing to the ChooseFortune service task. Automated tasks can be run
individually by the engine or run_automated_tasks
to run all waiting tasks.
execution.run_automated_tasks
Now, both paths are joined into one and execution is waiting at the script task. Notice, the results of previous tasks are merged into the process variables.
HelloWorld started * Flow_0ws7a4m
{
"name": "Eric",
"language": "it",
"formal": false,
"cookie": true,
"choose_greeting": {
"greeting": "Ciao"
},
"choose_fortune": "A foolish man listens to his heart. A wise man listens to cookies."
}
0 StartEvent Start: completed * out: Flow_080794y
1 UserTask IntroduceYourself: completed { "name": "Eric", "language": "it", "formal": false, "cookie": true } * in: Flow_080794y * out: Flow_0t9jhga
2 BoundaryEvent EggTimer: terminated
3 ParallelGateway Split: completed * in: Flow_0t9jhga * out: Flow_0gi9kt6, Flow_0q1vtg3
4 BusinessRuleTask ChooseGreeting: completed { "choose_greeting": { "greeting": "Ciao" } } * in: Flow_0gi9kt6 * out: Flow_1652shv
5 ExclusiveGateway WantsCookie: completed * in: Flow_0q1vtg3 * out: Flow_0pb7kh6
6 ServiceTask ChooseFortune: completed { "choose_fortune": "A foolish man listens to his heart. A wise man listens to cookies." } * in: Flow_0pb7kh6 * out: Flow_1iuc1xe
7 ParallelGateway Join: completed * in: Flow_1652shv, Flow_1iuc1xe * out: Flow_0ws7a4m
8 ScriptTask GenerateMessage: waiting * in: Flow_0ws7a4m
This time we'll run
the script task manually.
step = execution.step_by_element_id("GenerateMessage")
step.run
Now the process is complete.
HelloWorld completed *
{
"name": "Eric",
"language": "it",
"formal": false,
"cookie": true,
"choose_greeting": {
"greeting": "Ciao"
},
"choose_fortune": "A foolish man listens to his heart. A wise man listens to cookies.",
"message": "๐ Ciao Eric ๐ฅ A foolish man listens to his heart. A wise man listens to cookies."
}
0 StartEvent Start: completed * out: Flow_080794y
1 UserTask IntroduceYourself: completed { "name": "Eric", "language": "it", "formal": false, "cookie": true } * in: Flow_080794y * out: Flow_0t9jhga
2 BoundaryEvent EggTimer: terminated
3 ParallelGateway Split: completed * in: Flow_0t9jhga * out: Flow_0gi9kt6, Flow_0q1vtg3
4 BusinessRuleTask ChooseGreeting: completed { "choose_greeting": { "greeting": "Ciao" } } * in: Flow_0gi9kt6 * out: Flow_1652shv
5 ExclusiveGateway WantsCookie: completed * in: Flow_0q1vtg3 * out: Flow_0pb7kh6
6 ServiceTask ChooseFortune: completed { "choose_fortune": "A foolish man listens to his heart. A wise man listens to cookies." } * in: Flow_0pb7kh6 * out: Flow_1iuc1xe
7 ParallelGateway Join: completed * in: Flow_1652shv, Flow_1iuc1xe * out: Flow_0ws7a4m
8 ScriptTask GenerateMessage: completed { "message": "๐ A foolish man listens to his heart. A wise man listens to cookies." } * in: Flow_0ws7a4m * out: Flow_0gkfhvr
9 EndEvent End: completed * in: Flow_0gkfhvr
Execute:
$ bundle add spot_flow
Or install it directly:
$ gem install spot_flow
$ git clone ...
$ bin/setup
$ bin/rake
$ bin/guard
The gem is available as open source under the terms of the MIT License.
Developed by Connected Bits