camunda-workflow 0.1

data/lib/camunda/external_task_job.rb

@@ -0,0 +1,35 @@
+module Camunda::ExternalTaskJob
+  def perform(id, input_variables)
+    output_variables = bpmn_perform(input_variables)
+    output_variables = {} if output_variables.nil?
+    raise ArgumentError, "Expected a hash, got #{output_variables}" unless output_variables.is_a?(Hash)
+
+    report_completion id, output_variables
+  rescue Camunda::BpmnError => e
+    report_bpmn_error id, e
+  rescue StandardError => e
+    report_failure id, e, input_variables
+  end
+
+  def report_completion(id, variables)
+    # Submit to Camunda using
+    # POST /external-task/{id}/complete
+    Camunda::ExternalTask.new(id: id).complete(variables)
+  end
+
+  def report_failure(id, exception, input_variables)
+    # Submit error state to Camunda using
+    # POST /external-task/{id}/failure
+    Camunda::ExternalTask.new(id: id).failure(exception, input_variables)
+  end
+
+  def report_bpmn_error(id, exception)
+    # Submit bpmn error state to Camunda using
+    # POST /external-task/{id}/bpmnError
+    Camunda::ExternalTask.new(id: id).bpmn_error(exception)
+  end
+
+  def bpmn_perform(_variables)
+    raise StandardError, "Please define this method which takes a hash of variables and returns a hash of variables"
+  end
+end

data/lib/camunda/incident.rb

@@ -0,0 +1,3 @@
+class Camunda::Incident < Camunda::Model
+  collection_path 'incident'
+end

data/lib/camunda/matchers.rb

@@ -0,0 +1,20 @@
+RSpec::Matchers.define :have_topics do |topic_names|
+  match { |bpmn_xml| topic_names.sort == bpmn_xml.topics.sort }
+  failure_message { |bpmn_xml| "Expected #{topic_names}. Found #{bpmn_xml.topics.sort}" }
+end
+
+RSpec::Matchers.define :have_module do |module_name_expected|
+  match { |bpmn_xml| module_name_expected == bpmn_xml.module_name }
+  failure_message { |bpmn_xml| "ID of the BPMN process is #{bpmn_xml.module_name}. Expected #{module_name_expected}" }
+end
+
+RSpec::Matchers.define :have_defined_classes do
+  missing_classes = []
+  match do |bpmn_xml|
+    missing_classes = bpmn_xml.modularized_class_names.reject(&:safe_constantize)
+    missing_classes.empty?
+  end
+  failure_message do |_bpmn_xml|
+    "#{missing_classes} are not defined. They are the expected classes in your Rails app to implement the workers."
+  end
+end

data/lib/camunda/model.rb

@@ -0,0 +1,26 @@
+require 'her/model'
+class Camunda::Model
+  include Her::Model
+
+  api = lambda do
+    Her::API.new(url: File.join(Camunda::Workflow.configuration.engine_url)) do |c|
+      c.path_prefix = Camunda::Workflow.configuration.engine_route_prefix
+      # Request
+      c.use Faraday::Request::Multipart
+      c.use FaradayMiddleware::EncodeJson
+      # Response
+      c.use Faraday::Response::Logger, ActiveSupport::Logger.new(STDOUT), bodies: true if Rails.env.development?
+      c.use Her::Middleware::FirstLevelParseJSON
+
+      c.use Her::Middleware::SnakeCase
+      # Adapter
+      c.adapter :net_http
+    end
+  end
+
+  use_api api
+
+  def self.worker_id
+    Camunda::Workflow.configuration.worker_id
+  end
+end

data/lib/camunda/poller.rb

@@ -0,0 +1,8 @@
+class Camunda::Poller
+  def self.fetch_and_execute(topics, lock_duration: nil, long_polling_duration: nil)
+    loop do
+      Camunda::ExternalTask
+        .fetch_and_lock(topics, lock_duration: lock_duration, long_polling_duration: long_polling_duration).each(&:queue_task)
+    end
+  end
+end

data/lib/camunda/process_definition.rb

@@ -0,0 +1,29 @@
+class Camunda::ProcessDefinition < Camunda::Model
+  include Camunda::VariableSerialization
+  collection_path 'process-definition'
+
+  def self.start_by_key(key, hash={})
+    hash[:variables] = serialize_variables(hash[:variables]) if hash[:variables]
+    tenant_id = hash.delete(:tenant_id)
+    tenant_id ||= Camunda::Workflow.configuration.tenant_id
+
+    response = post_raw start_path_for_key(key, tenant_id), hash
+    raise Camunda::ProcessEngineException, response[:parsed_data][:data][:message] unless response[:response].status == 200
+
+    Camunda::ProcessInstance.new response[:parsed_data][:data]
+  end
+
+  def start(hash={})
+    hash[:variables] = serialize_variables(hash[:variables]) if hash[:variables]
+    response = self.class.post_raw "process-definition/#{id}/start", hash
+    raise Camunda::ProcessEngineException, response[:parsed_data][:data][:message] unless response[:response].status == 200
+
+    Camunda::ProcessInstance.new response[:parsed_data][:data]
+  end
+
+  def self.start_path_for_key(key, tenant_id)
+    path = "process-definition/key/#{key}"
+    path << "/tenant-id/#{tenant_id}" if tenant_id
+    "#{path}/start"
+  end
+end

data/lib/camunda/process_instance.rb

@@ -0,0 +1,21 @@
+class Camunda::ProcessInstance < Camunda::Model
+  collection_path 'process-instance'
+
+  def variables
+    response = self.class.get_raw "process-instance/#{id}/variables"
+    deserialize_variables response[:parsed_data][:data]
+  end
+
+  private
+
+  def deserialize_variables(hash)
+    hash.transform_values do |value_hash|
+      case value_hash[:type]
+      when "String", "Double", "Integer", "Boolean"
+        value_hash[:value]
+      when "Json"
+        value_hash[:value][:node_type]
+      end
+    end
+  end
+end

data/lib/camunda/signal.rb

@@ -0,0 +1,9 @@
+class Camunda::Signal < Camunda::Model
+  include Camunda::VariableSerialization
+  collection_path 'signal'
+
+  def self.create(hash={})
+    hash[:variables] = serialize_variables(hash[:variables]) if hash[:variables]
+    post_raw collection_path, hash
+  end
+end

data/lib/camunda/task.rb

@@ -0,0 +1,28 @@
+class Camunda::Task < Camunda::Model
+  include Camunda::VariableSerialization
+  collection_path 'task'
+
+  def self.find_by_business_key_and_task_definition_key!(instance_business_key, task_key)
+    find_by(instanceBusinessKey: instance_business_key, taskDefinitionKey: task_key).tap do |ct|
+      unless ct
+        raise MissingTask, "Could not find Camunda Task with processInstanceBusinessKey: #{instance_business_key} " \
+              "and taskDefinitionKey #{task_key}"
+      end
+    end
+  end
+
+  def self.mark_task_completed!(instance_business_key, task_key, variables={})
+    ct = find_by_business_key_and_task_definition_key!(instance_business_key, task_key)
+    ct.complete! variables
+  end
+
+  def complete!(vars)
+    self.class.post_raw("#{self.class.collection_path}/#{id}/complete", variables: serialize_variables(vars))[:response]
+        .tap do |response|
+      raise MissingTask unless response.success?
+    end
+  end
+
+  class MissingTask < StandardError
+  end
+end

data/lib/camunda/variable_serialization.rb

@@ -0,0 +1,48 @@
+require 'active_support/concern'
+module Camunda
+  module VariableSerialization
+    extend ActiveSupport::Concern
+
+    def serialize_variables(variables)
+      self.class.serialize_variables(variables)
+    end
+
+    class_methods do
+      # rubocop:disable Metrics/MethodLength
+      def serialize_variables(variables)
+        hash = variables.transform_values do |value|
+          case value
+          when String
+            { value: value, type: 'String' }
+          when Array, Hash
+            { value: transform_json(value).to_json, type: 'Json' }
+          when TrueClass, FalseClass
+            { value: value, type: 'Boolean' }
+          when Integer
+            { value: value, type: 'Integer' }
+          when Float
+            { value: value, type: 'Double' }
+          else
+            raise ArgumentError, "Not supporting complex types yet"
+          end
+        end
+        camelcase_keys(hash)
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      def transform_json(json)
+        if json.is_a?(Array)
+          json.map { |element| transform_json(element) }
+        elsif json.is_a?(Hash)
+          camelcase_keys(json)
+        else
+          json
+        end
+      end
+
+      def camelcase_keys(hash)
+        hash.deep_transform_keys { |key| key.to_s.camelcase(:lower) }
+      end
+    end
+  end
+end

data/lib/camunda/workflow.rb

@@ -0,0 +1,39 @@
+module Camunda
+  module Workflow
+    def self.configure
+      yield(configuration)
+    end
+
+    def self.configuration
+      @configuration ||= Configuration.new
+    end
+
+    class Configuration
+      attr_accessor :engine_url
+      attr_accessor :engine_route_prefix
+      attr_accessor :worker_id
+      attr_accessor :lock_duration
+      attr_accessor :max_polling_tasks
+      attr_accessor :long_polling_duration
+      attr_accessor :tenant_id
+
+      def initialize
+        @engine_url = 'http://localhost:8080'
+        @engine_route_prefix = 'rest-engine'
+        @worker_id = '0'
+        @lock_duration = 14.days
+        @max_polling_tasks = 2
+        @long_polling_duration = 30.seconds
+        @tenant_id = if defined?(Rails)
+                       Rails.env.test? ? 'test-environment' : nil
+                     end
+      end
+    end
+  end
+end
+
+%w[../camunda.rb variable_serialization.rb model.rb task.rb external_task.rb external_task_job.rb poller.rb process_definition.rb
+   process_instance.rb deployment.rb signal.rb bpmn_xml.rb incident.rb]
+  .each do |file|
+  require File.join(__dir__, file)
+end

data/lib/generators/camunda/bpmn_classes/USAGE

@@ -0,0 +1,10 @@
+Description:
+    Generates BPMN classes for a BPMN XML in the current Rails app. They will be under app/bpmn. It will first validate the
+    bpmn xml to make sure the class names are all populated as expected.
+
+Example:
+    rails generate camunda:bpmn_classes bpmn_file
+
+    This will create:
+        app/bpmn/#{process_key}/class1
+        app/bpmn/#{process_key}/class2

data/lib/generators/camunda/bpmn_classes/bpmn_classes_generator.rb

@@ -0,0 +1,67 @@
+module Camunda
+  module Generators
+    class BpmnClassesGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+      argument :bpmn_file, type: :string
+      class_option :model_path, type: :string, default: 'app/bpmn'
+
+      def validate_module_name
+        puts "The id of the BPMN process is: #{colored_module_name}. That will be your module name."
+        validate_constant_name(module_name)
+      end
+
+      def validate_class_names
+        bpmn_xml.modularized_class_names.each do |class_name|
+          validate_constant_name(class_name.demodulize, module_name)
+        end
+        puts set_color("External tasks with the same topic name as the BPMN id will be created.", :bold)
+        colorized_class_names = bpmn_xml.modularized_class_names.map! { |class_name| set_color class_name, :red }
+        puts colorized_class_names.join("\n")
+      end
+
+      def create_module
+        template 'bpmn_module.rb.template', File.join(model_path, "#{module_name.underscore}.rb")
+      end
+
+      def create_classes
+        bpmn_xml.class_names_with_same_bpmn_id_as_topic.each do |class_name|
+          template 'bpmn_class.rb.template',
+                   File.join(model_path, module_name.underscore, "#{class_name.underscore}.rb"), class_name: class_name
+        end
+      end
+
+      private
+
+      def validate_constant_name(name, module_name=nil)
+        top_level = module_name.nil? ? Module.new : module_name.constantize
+        colorized_name = set_color name, :red
+        begin
+          Object.const_set(name, top_level)
+        rescue NameError
+          puts "Cannot create a class/module with name #{colorized_name}. Not a valid name."
+          puts "You must set the ID in Camunda to be the name of a Ruby style constant"
+        end
+        return unless name.include?("_")
+
+        puts "Class name #{colorized_name} should not have an underscore _."
+        puts "Underscores are valid Ruby constant names, but likely you have not changed the name from the default."
+      end
+
+      def model_path
+        options['model_path']
+      end
+
+      def module_name
+        @module_name ||= bpmn_xml.module_name
+      end
+
+      def bpmn_xml
+        @bpmn_xml ||= BpmnXML.new(File.open(bpmn_file))
+      end
+
+      def colored_module_name
+        @colored_module_name ||= set_color module_name, :red
+      end
+    end
+  end
+end

data/lib/generators/camunda/bpmn_classes/templates/bpmn_class.rb.template

@@ -0,0 +1,10 @@
+module <%= module_name %>
+  class <%= config[:class_name] %> < CamundaJob
+    include <%= module_name %>
+
+    def bpmn_perform(_variables)
+      raise StandardError,
+        "Please define this method to perform your task which takes a hash of variables and returns a hash of variables"
+    end
+  end
+end

data/lib/generators/camunda/bpmn_classes/templates/bpmn_module.rb.template

@@ -0,0 +1,5 @@
+module <%= module_name %>
+  # You can use this module for shared behavior. You may also use ActiveSupport::Concern if you wish.
+  # That means it not only acts as a namespace, but can be be included in a class to let this module behave as a mixin.
+  # extend ActiveSupport::Concern
+end

data/lib/generators/camunda/install/USAGE

@@ -0,0 +1,10 @@
+Description:
+    One time install of ActiveJob integrations for Camunda jobs
+
+Example:
+    rails generate camunda:install
+
+    This will create:
+        app/jobs/camunda_job.rb
+
+    which includes Camunda::ExternalTaskJob. It can be further customized

data/lib/generators/camunda/install/install_generator.rb

@@ -0,0 +1,11 @@
+module Camunda
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      def copy_camunda_application_job
+        copy_file 'camunda_job.rb', 'app/jobs/camunda_job.rb'
+      end
+    end
+  end
+end

data/lib/generators/camunda/install/templates/camunda_job.rb

@@ -0,0 +1,7 @@
+class CamundaJob < ApplicationJob
+  # If using Sidekiq change to include Sidekiq::Worker instead of inheriting from ApplicationJob
+  include Camunda::ExternalTaskJob
+  # queue_as :camunda
+
+  # Customize if needed for your Camunda background task instances
+end

data/lib/generators/camunda/spring_boot/USAGE

@@ -0,0 +1,12 @@
+Description:
+    One time install of Java Camunda application to do unit testing of your BPMN process
+
+Example:
+    rails generate camunda:unit_tests
+
+    This will create a Java app in:
+        bpmn/java_app
+
+    with a sample BPMN file and Unit Test.
+
+    The suggested location for your BPMN file is in `bpmn/diagrams`. `bpmn/java_app/src/main/resources` is a symlink to that.

data/lib/generators/camunda/spring_boot/spring_boot_generator.rb

@@ -0,0 +1,69 @@
+module Camunda
+  module Generators
+    class SpringBootGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+      class_option :app_path, type: :string, default: 'bpmn/java_app'
+      class_option :diagram_path, type: :string, default: 'bpmn/diagrams'
+
+      def copy_java_app_files
+        copy_file 'pom.xml', File.join(bpmn_app_path, 'pom.xml')
+        copy_file 'camunda.cfg.xml', File.join(bpmn_app_path, 'src/test/resources/camunda.cfg.xml')
+        copy_file 'application.properties', File.join(bpmn_app_path, 'src/main/resources/application.properties')
+        copy_file 'ProcessScenarioTest.java', File.join(bpmn_app_path, 'src/test/java/unittest/ProcessScenarioTest.java')
+        copy_file 'Camunda.java', File.join(bpmn_app_path, 'src/main/java/camunda/Camunda.java')
+      end
+
+      def link_resources_folder
+        copy_file 'sample.bpmn', File.join(diagram_path, 'sample.bpmn'), ''
+      end
+
+      def add_to_ignores
+        %w[.gitignore .cfignore].each do |file|
+          append_to_file file do
+            "\n# BPMN Java app\n" +
+              File.join(bpmn_app_path, 'target') +
+              "\n"
+          end
+        end
+      end
+
+      def output_error_instructions
+        puts <<~DOC
+          If you get an error when starting your Rails app
+
+          ** ERROR: directory is already being watched! **
+
+          Directory: bpmn/java_app/src/main/resources
+          is already being watched through: bpmn/diagrams
+
+          MORE INFO: https://github.com/guard/listen/wiki/Duplicate-directory-errors
+
+          It is because ActionMailer preview causes test/mailers/previews to get added to the Rails EventedFileChecker
+          by default. RSpec is supposed to override it, but it is not overridden properly for EventedFileChecker and/or
+          you don't have spec/mailers/preview existing. If that directory does not exist it goes to the first common
+          directory that exists which is your Rails root folder.
+
+          So EventedFileChecker is listening to your entire Rails folder. Not a big problem, but it causes a problem
+          for our created symlink.
+
+          So add:
+
+             config.action_mailer.show_previews = false
+
+          to your development.rb file to solve Listen errors about a symlink. Unless you are using ActionMailer
+          previews in which case you should have the directory created already.
+        DOC
+      end
+
+      private
+
+      def bpmn_app_path
+        options['app_path']
+      end
+
+      def diagram_path
+        options['diagram_path']
+      end
+    end
+  end
+end