spot_flow 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ec2c62e8ee6f2863a951627cfe2733f5d015feb981cd036bbabff22c7d681ea0
+  data.tar.gz: 416207e69a02f5c8ba3308369c46bdcc783a162ed9eb45ef1f8788ec6dbc0dc7
+SHA512:
+  metadata.gz: 0a0526b9ef739fdb028d6864f4144a9e7e58da25eca2553acfe82933175c82d3d85818e12f33884a5e9efda650b78698aefb093dbd4a70347952a178dc4cd436
+  data.tar.gz: 16c1a43d577b831a774c57e748e57c78c6750eec256aef6bf9cbf5991996aa33fdacf33ecbc37e2e327c21573b525dd2bafffc6dc58216e938fa3729d848f70b

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2022 Connected Bits, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,187 @@
+# Spot Flow
+
+Spot Flow is a workflow engine for Rails applications based on the [bpmn](https://www.bpmn.org) standard. It executes business processes defined in a [modeler](https://camunda.com/download/modeler/). It uses [Spot Feel](https://github.com/connectedbits/spot-feel) to evaluate expressions and business rules in the BPMN model. It can be used with [Spot Form](https://github.com/connectedbits/spot-form) to render dynamic forms for user tasks.
+
+## Usage
+
+The engine executes business processes like [this one](/test/fixtures/files/hello_world.bpmn).
+
+![Example](test/fixtures/files/hello_world.png)
+
+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`.
+
+```ruby
+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.
+
+```ruby
+execution.print
+```
+
+```ruby
+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.
+
+```ruby
+# 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.
+
+```ruby
+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.
+
+```ruby
+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.
+
+```ruby
+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.
+
+```ruby
+step = execution.step_by_element_id("GenerateMessage")
+step.run
+```
+
+Now the process is complete.
+
+```ruby
+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
+```
+
+## Documentation
+
+- [Processes](/docs/processes.md)
+- [Tasks](/docs/tasks.md)
+- [Events](/docs/events.md)
+- [Event Definitions](/docs/event_definitions.md)
+- [Gateways](/docs/gateways.md)
+- [Expressions](/docs/expressions.md)
+- [Data Flow](/docs/data_flow.md)
+- [Execution](/docs/execution.md)
+
+## Installation
+
+Execute:
+
+```bash
+$ bundle add spot_flow
+```
+
+Or install it directly:
+
+```bash
+$ gem install spot_flow
+```
+
+## Development
+
+```bash
+$ git clone ...
+$ bin/setup
+$ bin/rake
+$ bin/guard
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+Developed by [Connected Bits](http://www.connectedbits.com)

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/setup"
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test

data/lib/spot_flow/bpmn/definitions.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module SpotFlow
+  module Bpmn
+    class Definitions
+      include ActiveModel::Model
+
+      attr_accessor :id, :name, :target_namespace, :exporter, :exporter_version, :execution_platform, :execution_platform_version
+      attr_reader :messages, :signals, :errors, :processes
+
+      def self.from_xml(xml)
+        XmlHasher.configure do |config|
+          config.snakecase = true
+          config.ignore_namespaces = true
+          config.string_keys = false
+        end
+        hash = XmlHasher.parse(xml)
+        Definitions.new(hash[:definitions].except(:bpmn_diagram)).tap do |definitions|
+          definitions.processes.each do |process|
+            process.wire_references(definitions)
+          end
+        end
+      end
+
+      def initialize(attributes={})
+        super(attributes.except(:message, :signal, :error, :process))
+
+        @messages = Array.wrap(attributes[:message]).map { |atts| Message.new(atts) }
+        @signals = Array.wrap(attributes[:signal]).map { |atts| Signal.new(atts) }
+        @errors = Array.wrap(attributes[:error]).map { |atts| Error.new(atts) }
+        @processes = Array.wrap(attributes[:process]).map { |atts| Process.new(atts) }
+      end
+
+      def message_by_id(id)
+        messages.find { |message| message.id == id }
+      end
+
+      def signal_by_id(id)
+        signals.find { |signal| signal.id == id }
+      end
+
+      def error_by_id(id)
+        errors.find { |error| error.id == id }
+      end
+
+      def process_by_id(id)
+        processes.find { |process| process.id == id }
+      end
+
+      def inspect
+        "#<Bpmn::Definitions @id=#{id.inspect} @name=#{name.inspect} @messages=#{messages.inspect} @signals=#{signals.inspect} @errors=#{errors.inspect} @processes=#{processes.inspect}>"
+      end
+    end
+  end
+end

data/lib/spot_flow/bpmn/element.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module SpotFlow
+  module Bpmn
+    class Element
+      include ActiveModel::Model
+
+      attr_accessor :id, :name, :extension_elements
+
+      def initialize(attributes = {})
+        super(attributes.slice(:id, :name))
+
+        @extension_elements = ExtensionElements.new(attributes[:extension_elements]) if attributes[:extension_elements].present?
+      end
+
+      def inspect
+        "#<#{self.class.name.gsub(/SpotFlow::/, "")} @id=#{id.inspect} @name=#{name.inspect}>"
+      end
+    end
+
+    class Message < Element
+    end
+
+    class Signal < Element
+    end
+
+    class Error < Element
+    end
+
+    class Collaboration < Element
+    end
+
+    class LaneSet < Element
+    end
+
+    class Participant < Element
+      attr_accessor :process_ref, :process
+
+      def initialize(attributes = {})
+        super(attributes.except(:process_ref))
+      end
+    end
+  end
+end

data/lib/spot_flow/bpmn/event.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+module SpotFlow
+  module Bpmn
+    class Event < Step
+      attr_accessor :event_definitions
+
+      def initialize(attributes = {})
+        super(attributes.except(:message_event_definition, :signal_event_definition, :error_event_definition, :terminate_event_definition, :timer_event_definition))
+
+        @event_definitions = []
+
+        Array.wrap(attributes[:message_event_definition]).each do |med|
+          @event_definitions.push MessageEventDefinition.new(med)
+        end if attributes[:message_event_definition].present?
+
+        Array.wrap(attributes[:signal_event_definition]).each do |sed|
+          @event_definitions.push SignalEventDefinition.new(sed)
+        end if attributes[:signal_event_definition].present?
+
+        Array.wrap(attributes[:error_event_definition]).each do |eed|
+          @event_definitions.push ErrorEventDefinition.new(eed)
+        end if attributes[:error_event_definition].present?
+
+        Array.wrap(attributes[:terminate_event_definition]).each do |ted|
+          @event_definitions.push TerminateEventDefinition.new(ted)
+        end if attributes[:terminate_event_definition].present?
+
+        Array.wrap(attributes[:timer_event_definition]).each do |ted|
+          @event_definitions.push TimerEventDefinition.new(ted)
+        end if attributes[:timer_event_definition].present?
+      end
+
+      def event_definition_ids
+        event_definitions.map(&:id)
+      end
+
+      def is_catching?
+        false
+      end
+
+      def is_throwing?
+        false
+      end
+
+      def is_none?
+        event_definitions.empty?
+      end
+
+      def is_conditional?
+        conditional_event_definition.present?
+      end
+
+      def is_escalation?
+        escalation_event_definition.present?
+      end
+
+      def is_error?
+        error_event_definition.present?
+      end
+
+      def is_message?
+        !message_event_definitions.empty?
+      end
+
+      def is_signal?
+        !signal_event_definitions.empty?
+      end
+
+      def is_terminate?
+        terminate_event_definition.present?
+      end
+
+      def is_timer?
+        timer_event_definition.present?
+      end
+
+      def conditional_event_definition
+        event_definitions.find { |ed| ed.is_a?(ConditionalEventDefinition) }
+      end
+
+      def escalation_event_definition
+        event_definitions.find { |ed| ed.is_a?(EscalationEventDefinition) }
+      end
+
+      def error_event_definitions
+        event_definitions.select { |ed| ed.is_a?(ErrorEventDefinition) }
+      end
+
+      def error_event_definition
+        event_definitions.find { |ed| ed.is_a?(ErrorEventDefinition) }
+      end
+
+      def message_event_definitions
+        event_definitions.select { |ed| ed.is_a?(MessageEventDefinition) }
+      end
+
+      def signal_event_definitions
+        event_definitions.select { |ed| ed.is_a?(SignalEventDefinition) }
+      end
+
+      def terminate_event_definition
+        event_definitions.find { |ed| ed.is_a?(TerminateEventDefinition) }
+      end
+
+      def timer_event_definition
+        event_definitions.find { |ed| ed.is_a?(TimerEventDefinition) }
+      end
+
+      def execute(execution)
+        event_definitions.each { |event_definition| event_definition.execute(execution) }
+      end
+    end
+
+    class StartEvent < Event
+
+      def is_catching?
+        true
+      end
+
+      def execute(execution)
+        super
+        leave(execution)
+      end
+    end
+
+    class IntermediateThrowEvent < Event
+
+      def is_throwing?
+        true
+      end
+
+      def execute(execution)
+        super
+        leave(execution)
+      end
+    end
+
+    class IntermediateCatchEvent < Event
+
+      def is_catching?
+        true
+      end
+
+      def execute(execution)
+        super
+        execution.wait
+      end
+
+      def signal(execution)
+        leave(execution)
+      end
+    end
+
+    class BoundaryEvent < Event
+      attr_accessor :attached_to_ref, :attached_to, :cancel_activity
+
+      def initialize(attributes = {})
+        super(attributes.except(:attached_to_ref, :cancel_activity))
+
+        @attached_to_ref = attributes[:attached_to_ref]
+        @cancel_activity = true
+        if attributes[:cancel_activity].present?
+          @cancel_activity = attributes[:cancel_activity] == "false" ? false : true
+        end
+      end
+
+      def is_catching?
+        true
+      end
+
+      def execute(execution)
+        super
+        execution.wait
+      end
+
+      def signal(execution)
+        execution.attached_to.terminate if cancel_activity
+        leave(execution)
+      end
+    end
+
+    class EndEvent < Event
+
+      def is_throwing?
+        true
+      end
+
+      def execute(execution)
+        super
+        execution.end(true)
+      end
+    end
+  end
+end

data/lib/spot_flow/bpmn/event_definition.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module SpotFlow
+  module Bpmn
+    class EventDefinition < Element
+      def execute(execution)
+      end
+    end
+
+    class ConditionalEventDefinition < EventDefinition
+      attr_accessor :variable_name, :variable_events, :condition
+
+      def initialize(attributes = {})
+        super(attributes.except(:variable_name, :variable_events, :condition))
+
+        @variable_name = moddle[:variable_name] # "var1"
+        @variable_events = moddle[:variable_events] # "create, update"
+        @condition = moddle[:condition] # var1 = 1
+      end
+    end
+
+    class EscalationEventDefinition < EventDefinition
+    end
+
+    class ErrorEventDefinition < EventDefinition
+      attr_accessor :error_ref, :error
+      attr_accessor :error_code_variable, :error_message_variable
+
+      def initialize(attributes = {})
+        super(attributes.except(:error_ref, :error_code_variable, :error_message_variable))
+
+        @error_ref = attributes[:error_ref]
+        @error_code_variable = attributes[:error_code_variable]
+        @error_message_variable = attributes[:error_message_variable]
+      end
+
+      def execute(execution)
+        if execution.step.is_throwing?
+          execution.throw_error(error_name)
+        else
+          execution.error_names.push error_name
+        end
+      end
+
+      def error_id
+        error&.id
+      end
+
+      def error_name
+        error&.name
+      end
+    end
+
+    class MessageEventDefinition < EventDefinition
+      attr_accessor :message_ref, :message
+
+      def initialize(attributes = {})
+        super(attributes.except(:message_ref))
+
+        @message_ref = attributes[:message_ref]
+      end
+
+      def execute(execution)
+        if execution.step.is_throwing?
+          execution.throw_message(message_name)
+        else
+          execution.message_names.push message_name
+        end
+      end
+
+      def message_id
+        message&.id
+      end
+
+      def message_name
+        message&.name
+      end
+    end
+
+    class SignalEventDefinition < EventDefinition
+      attr_accessor :signal_ref, :signal
+
+      def initialize(attributes = {})
+        super(attributes.except(:signal_ref))
+
+        @signal_ref = moddle[:signal_ref]
+      end
+
+      def signal_id
+        signal&.id
+      end
+
+      def signal_name
+        signal&.name
+      end
+    end
+
+    class TerminateEventDefinition < EventDefinition
+
+      def execute(execution)
+        execution.parent&.terminate
+      end
+    end
+
+    class TimerEventDefinition < EventDefinition
+      attr_accessor :time_date, :time_duration_type, :time_duration, :time_cycle
+
+      def initialize(attributes = {})
+        super(attributes.except(:time_date, :time_duration, :time_cycle))
+
+        @time_duration_type = attributes[:time_duration_type]
+        @time_duration = attributes[:time_duration]
+      end
+
+      def execute(execution)
+        if execution.step.is_catching?
+          execution.timer_expires_at = time_due
+        end
+      end
+
+      private
+
+      def time_due
+        # Return the next time the timer is due
+        if time_date
+          return Date.parse(time_date)
+        elsif time_duration
+          return Time.zone.now + ActiveSupport::Duration.parse(time_duration)
+        else
+          return Time.zone.now # time_cycle not yet implemented
+        end
+      end
+    end
+  end
+end

data/lib/spot_flow/bpmn/extension_elements.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module SpotFlow
+  module Bpmn
+    class ExtensionElements
+      VALID_EXTENSION_NAMESPACES = %w[zeebe]
+
+      attr_accessor :assignment_definition, :called_element, :called_decision, :form_definition, :io_mapping, :properties, :script, :subscription, :task_definition, :task_headers, :task_schedule
+
+      def initialize(attributes = {})
+        if attributes[:properties].present?
+          @properties = HashWithIndifferentAccess.new
+          Array.wrap(attributes[:properties][:property]).each { |property_moddle| @properties[property_moddle[:name]] = property_moddle[:value] }
+        end
+
+        @assignment_definition = Zeebe::AssignmentDefinition.new(attributes[:assignment_definition]) if attributes[:assignment_definition].present?
+        @called_element = Zeebe::CalledElement.new(attributes[:called_element]) if attributes[:called_element].present?
+        @called_decision = Zeebe::CalledDecision.new(attributes[:called_decision]) if attributes[:called_decision].present?
+        @form_definition = Zeebe::FormDefinition.new(attributes[:form_definition]) if attributes[:form_definition].present?
+        @io_mapping = Zeebe::IoMapping.new(attributes[:io_mapping]) if attributes[:io_mapping].present?
+        @script = Zeebe::Script.new(attributes[:script]) if attributes[:script].present?
+        @subscription = Zeebe::Subscription.new(attributes[:subscription]) if attributes[:subscription].present?
+        @task_definition = Zeebe::TaskDefinition.new(attributes[:task_definition]) if attributes[:task_definition].present?
+        @task_headers = Zeebe::TaskHeaders.new(attributes[:task_headers]) if attributes[:task_headers].present?
+        @task_schedule = Zeebe::TaskSchedule.new(attributes[:task_schedule]) if attributes[:task_schedule].present?
+      end
+    end
+  end
+end