camunda-workflow 0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ef3a0dbf5313cc35e1dbee9a13fb1224dbec5f592bb24449c5e098db593797d6
+  data.tar.gz: 1315511b21e6aa52e614e9610bb51e905301ba2bffb9453978cfffb35242bddc
+SHA512:
+  metadata.gz: e6392d9dea74d826d93479f34a382e79717cc50f906f0d7f88f246c6d1f79174f6a9a7399898e263d9e8017708517991e752833b99db01f41db6ecb29451bd4f
+  data.tar.gz: d08d0468fad93654ddbb940161c0248d88e7e67a496bb6c547a276aa2d24ffe3c6c7e851eca916a1d5af4ebb20244daafd4468f08a4fe6cfaba4dd418e01532d

data/CONTRIBUTING.md

@@ -0,0 +1,20 @@
+## Contributing
+
+### Instructions
+Please create an issue to track what you are working on and ensure it is relevant.
+
+Make sure whatever you are adding has specs. We should be able to maintain 100% coverage.
+
+### Camunda interactions
+
+We are using VCR to record interactions with a local Camunda engine. If you wish to try this run a camunda engine listening on `/rest`. `/rest` is the default of the spring boot application that we generate with this gem. This is different from the default `/rest-engine` of the default downloadable distribution.
+
+You can for instance upgrade the Camunda version, delete the `spec/vcr` folder and then re-run the specs with `bundle exec rspec`
+
+## Public domain
+
+This project is in the worldwide [public domain](LICENSE.md). As stated in [CONTRIBUTING](CONTRIBUTING.md):
+
+> This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the [CC0 1.0 Universal public domain dedication](https://creativecommons.org/publicdomain/zero/1.0/).
+>
+> All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.

data/LICENSE.md

@@ -0,0 +1,31 @@
+As a work of the United States Government, this project is in the
+public domain within the United States.
+
+Additionally, we waive copyright and related rights in the work
+worldwide through the CC0 1.0 Universal public domain dedication.
+
+## CC0 1.0 Universal Summary
+
+This is a human-readable summary of the [Legal Code (read the full text)](https://creativecommons.org/publicdomain/zero/1.0/legalcode).
+
+### No Copyright
+
+The person who associated a work with this deed has dedicated the work to
+the public domain by waiving all of his or her rights to the work worldwide
+under copyright law, including all related and neighboring rights, to the
+extent allowed by law.
+
+You can copy, modify, distribute and perform the work, even for commercial
+purposes, all without asking permission.
+
+### Other Information
+
+In no way are the patent or trademark rights of any person affected by CC0,
+nor are the rights that other persons may have in the work or in how the
+work is used, such as publicity or privacy rights.
+
+Unless expressly stated otherwise, the person who associated a work with
+this deed makes no warranties about the work, and disclaims liability for
+all uses of the work, to the fullest extent permitted by applicable law.
+When using or citing the work, you should not imply endorsement by the
+author or the affirmer.

data/README.md

@@ -0,0 +1,209 @@
+[![Build Status](https://travis-ci.com/amalagaura/camunda-workflow.svg?branch=master)](https://travis-ci.com/amalagaura/camunda-workflow)
+# Camunda Workflow
+
+## An opinionated interface to Camunda for Ruby/Rails apps
+
+[Her](https://github.com/remiprev/her) is used to communicate with the [Camunda REST API](https://docs.camunda.org/manual/latest/reference/rest/). 
+
+### Add to your Gemfile
+```ruby
+  gem 'camunda-workflow'
+```
+
+## Camunda Integration with Ruby
+The process definitions key becomes the module name of your implementation classes and must be set to the name of a ruby style constant (screenshot example provided below). This same process definition key should be set as the topic name for external tasks. Tasks are pulled and fetched and locked and then run. We expect classes (ActiveJob) to implement each external task.
+    
+![image](https://www.evernote.com/l/Ajnoawx6CYhKha7OXUPkyeo6CjrxvSoTgOUB/image.png)
+
+### Integration with your worker classes
+
+The module `ExternalTaskJob` should be included in your job implementation classes. The job implementation classes can inherit from `ActiveJob::Base`, or use `Sidekiq::Worker` or use some other system for job queuing.
+
+Currently we call `perform_later` on job implementation classes. If we want to make this more flexible, we need to make the method used to queue jobs configurable. `perform_later` for ActiveJob, `perform_async` for Sidekiq, or `perform` if no background task system is used.
+
+### Implementing `bpmn_perform`
+
+`bpmn_perform` is your implementation of the service task.
+
+### Supporting bpmn exceptions
+
+Camunda supports throwing bpmn exceptions on a service task to communicate logic errors and not underlying code errors. These expected errors are thrown with 
+```ruby
+raise Camunda::BpmnError.new error_code: 'bpmn-error', message: "Special BPMN error", variables: { bpmn: 'error' }
+```
+
+## Generators
+
+### BPMN ActiveJob install
+```bash
+rails generate camunda:install
+```
+
+Creates `app/jobs/camunda_job.rb`. A class which inherits from ApplicationJob and includes `ExternalTaskJob`. It can be changed to include
+ Sidekiq::Worker instead.  
+
+All of the BPMN worker classes will inherit from this class
+
+### Java Spring Boot App install
+```bash
+rails generate camunda:spring_boot
+```
+Creates a skeleton Java Spring Boot app, which also contains the minimal files to run unit tests on a BPMN file. This can be used to
+start a Camunda instance with a REST api. This can also be deployed to PCF by generating a Spring Boot jar and pushing it.
+
+### BPMN Classes
+```bash
+rails generate camunda:bpmn_classes
+```
+
+Parses the BPMN file and creates task classes according to the ID of the process file and the ID of 
+each task. It checks each task and only creates it if the topic name is the same as the process ID. This 
+allows one to have some tasks be handled outside the Rails app. It confirms that the ID's are valid Ruby constant names. 
+
+#### Starting the Camunda server for development
+
+Start the application: `mvn spring-boot:run`
+
+Camunda-workflow defaults to an in-memory, h2 database engine. If you rather use a Postgres database engine, comment out the 
+h2 database engine settings in the `pom.xml` file located in `bpmn/java_app`. Default settings for using Postgres are available in the `pom.xml` file. 
+You will need to create a Postgres database on localhost called `camunda`. 
+
+#### Engine Route Prefix using the Java Spring Boot app
+The default engine route prefix for the provided Java Spring Boot app is `rest`. If you choose to download and use the Camunda distribution,
+the engine prefix is `rest-engine`. Camunda-workflow is configured to use `rest-engine`.
+
+To override the default engine route prefix to allow your rails application to use the route prefix of `rest`, you need to add an initializer file
+in your rails app with the below code. 
+
+
+```ruby
+# filename initializers/camunda.rb
+Camunda::Workflow.configure do |config|
+  config.engine_route_prefix = 'rest'
+end
+```
+
+#### Generating a jar for deployment
+`mvn package spring-boot:repackage`
+
+The jar is in `target/camunda-bpm-springboot.jar`
+
+#### Deploying to PCF
+`cf push app_name -p target/camunda-bpm-springboot.jar`
+
+It will fail to start. Create a postgres database as a service in PCF and bind it to the application. The Springboot application is configured for Postgres and will then be able to start.
+
+#### Running java unit tests
+`mvn clean test`
+
+## Usage
+### Deploying a model
+Uses a default name, etc. Below outlines how to deploy a process using the included sample.bpmn
+file created by the generator. Alternatively you can deploy using Camunda Modeler
+
+```ruby
+  Camunda::Deployment.create file_name: 'bpmn/diagrams/sample.bpmn'
+```
+### Processes
+
+#### Starting a process
+
+```ruby
+  start_response = Camunda::ProcessDefinition.start_by_key'CamundaWorkflow', variables: { x: 'abcd' }, businessKey: 'WorkflowBusinessKey'
+```
+**Camunda cannot handle snake case variables, all snake_case variables are serialized to camelCase before a request is sent to the REST api. Variables returned back from the Camunda API will be deserialized back to snake_case.**
+
+`{ my_variable: "xyz" }`
+
+will be converted to:
+
+`{ myVariable: "xyz" }`
+
+#### Destroy a process
+```ruby
+  Camunda::ProcessInstance.destroy_existing start_response.id
+```
+
+### Tasks
+
+#### Fetch tasks and queue with ActiveJob
+
+The poller will run as an infinite loop with long polling to fetch tasks, queue, and run them. Topic is the process definition key, 
+as show in the screenshot example from the Camunda Modeler.
+
+Below will run the poller to fetch, lock, and run a task for the example process definition located in 
+the `starting a process` detailed above.
+
+```ruby
+  Camunda::Poller.fetch_and_execute %w[CamundaWorkflow]
+```
+
+#### Fetch tasks 
+For testing from the console
+
+```ruby
+  tasks = Camunda::ExternalTask.fetch_and_lock %w[CamundaWorkflow]
+``` 
+
+#### Run a task
+
+```ruby
+  tasks.each(&:run_now)
+```
+
+
+### User Tasks
+#### Mark a user task complete
+```ruby
+  Camunda::Task.mark_task_completed!(business_key, task_key, {})
+```
+
+### Rspec Helpers
+RSpec helpers can will validate your application to make sure it has a class for every External task in a given BPMN file.
+```ruby
+require 'camunda/matchers'
+
+RSpec.describe "BPMN Diagrams" do
+  describe Camunda::BpmnXML.new(File.open("bpmn/diagrams/YourFile.bpmn")) do
+    it { is_expected.to have_module('YourModule') }
+    it { is_expected.to have_topics(%w[YourModule]) }
+    it { is_expected.to have_defined_classes }
+  end
+end
+```
+#### Note: 
+
+If you get an error
+  
+        ** 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
+appropriately overridden 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.
+
+## Contributing
+
+See [CONTRIBUTING](CONTRIBUTING.md) for additional information.
+
+## Public domain
+
+This project is in the worldwide [public domain](LICENSE.md). As stated in [CONTRIBUTING](CONTRIBUTING.md):
+
+> This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the [CC0 1.0 Universal public domain dedication](https://creativecommons.org/publicdomain/zero/1.0/).
+>
+> All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.

data/lib/camunda.rb

@@ -0,0 +1,54 @@
+require 'active_support/core_ext/string/inflections.rb'
+require 'active_support/core_ext/object/blank.rb'
+require 'her'
+require 'faraday'
+require 'faraday_middleware'
+
+module Camunda
+  class << self
+    attr_writer :logger
+
+    def logger
+      @logger ||= Logger.new($stdout).tap do |log|
+        log.progname = name
+      end
+    end
+  end
+
+  class Her::Middleware::SnakeCase < Faraday::Response::Middleware
+    def on_complete(env)
+      return if env[:body].blank?
+
+      json = JSON.parse(env[:body])
+      if json.is_a?(Array)
+        json.map { |hash| transform_hash!(hash) }
+      elsif json.is_a?(Hash)
+        transform_hash!(json)
+      end
+      env[:body] = JSON.generate(json)
+    end
+
+    def transform_hash!(hash)
+      hash.deep_transform_keys!(&:underscore)
+    end
+  end
+
+  class MissingImplementationClass < StandardError
+    def initialize(class_name)
+      super "Class to run a Camunda activity does not exist. Ensure there is a class with name: #{class_name} available."
+    end
+  end
+
+  class ProcessEngineException < StandardError
+  end
+
+  class BpmnError < StandardError
+    attr_reader :error_code, :variables
+
+    def initialize(message:, error_code:, variables: {})
+      super(message)
+      @error_code = error_code
+      @variables = variables
+    end
+  end
+end

data/lib/camunda/bpmn_xml.rb

@@ -0,0 +1,52 @@
+class Camunda::BpmnXML
+  attr_reader :doc
+  def initialize(io_or_string)
+    @doc = Nokogiri::XML(io_or_string)
+  end
+
+  def to_s
+    module_name
+  end
+
+  def module_name
+    @doc.xpath('/bpmn:definitions/bpmn:process').first['id']
+  end
+
+  def external_tasks
+    @doc.xpath('//*[@camunda:type="external"]').map do |task|
+      Task.new(task)
+    end
+  end
+
+  def class_names_with_same_bpmn_id_as_topic
+    tasks_with_same_bpmn_id_as_topic.map(&:class_name)
+  end
+
+  def modularized_class_names
+    class_names_with_same_bpmn_id_as_topic.map { |name| "#{module_name}::#{name}" }
+  end
+
+  def topics
+    @doc.xpath('//*[@camunda:topic]').map { |node| node.attribute('topic').value }.uniq
+  end
+
+  private
+
+  def tasks_with_same_bpmn_id_as_topic
+    external_tasks.select { |task| task.topic == module_name }
+  end
+
+  class Task
+    def initialize(task)
+      @task = task
+    end
+
+    def class_name
+      @task.attribute('id').value
+    end
+
+    def topic
+      @task.attribute('topic').value
+    end
+  end
+end

data/lib/camunda/deployment.rb

@@ -0,0 +1,29 @@
+class Camunda::Deployment < Camunda::Model
+  collection_path 'deployment'
+  # Only supporting .create which uses a POST on deployment/create.
+  def self.create(file_names:, tenant_id: nil, deployment_source: 'Camunda Workflow Gem', deployment_name: nil)
+    deployment_name ||= file_names.map { |file_name| File.basename(file_name) }.join(", ")
+    tenant_id ||= Camunda::Workflow.configuration.tenant_id
+    args = file_data(file_names).merge('deployment-name' => deployment_name, 'deployment-source' => deployment_source)
+    args.merge!("tenant-id": tenant_id) if tenant_id
+    response = post_raw('deployment/create', args)
+
+    deployed_process_definitions(response[:parsed_data][:data][:deployed_process_definitions])
+  end
+
+  def self.file_data(file_names)
+    file_names.map do |file_name|
+      [file_name, UploadIO.new(file_name, 'text/plain')]
+    end.to_h
+  end
+
+  def self.deployed_process_definitions(definitions_hash)
+    # Currently only returning the process definitions. But this Deployment.create can create a DMN, CMMN also
+    # It returns :deployed_process_definitions, :deployed_case_definitions, :deployed_decision_definitions,
+    # :deployed_decision_requirements_definitions
+
+    raise Camunda::ProcessEngineException, "No Process Definition created" if definitions_hash.nil?
+
+    definitions_hash.values.map { |process_definition| Camunda::ProcessDefinition.new process_definition }
+  end
+end

data/lib/camunda/external_task.rb

@@ -0,0 +1,83 @@
+require 'active_support/core_ext/string/inflections.rb'
+
+class Camunda::ExternalTask < Camunda::Model
+  include Camunda::VariableSerialization
+  collection_path 'external-task'
+  custom_post :fetchAndLock, :unlock
+
+  def self.long_polling_duration
+    Camunda::Workflow.configuration.long_polling_duration.in_milliseconds
+  end
+
+  def self.max_polling_tasks
+    Camunda::Workflow.configuration.max_polling_tasks
+  end
+
+  def self.lock_duration
+    Camunda::Workflow.configuration.lock_duration.in_milliseconds
+  end
+
+  def failure(exception, input_variables)
+    variables_information = "Input variables are #{input_variables.inspect}\n\n"
+    self.class.post_raw("#{collection_path}/#{id}/failure",
+                        workerId: worker_id, errorMessage: exception.message,
+                        errorDetails: variables_information + exception.full_message)[:response]
+  end
+
+  def bpmn_error(bpmn_exception)
+    self.class.post_raw("#{collection_path}/#{id}/bpmnError",
+                        workerId: worker_id, variables: serialize_variables(bpmn_exception.variables),
+                        errorCode: bpmn_exception.error_code, errorMessage: bpmn_exception.message)[:response]
+  end
+
+  def complete(variables={})
+    self.class.post_raw("#{collection_path}/#{id}/complete",
+                        workerId: worker_id, variables: serialize_variables(variables))[:response]
+  end
+
+  def worker_id
+    self.class.worker_id
+  end
+
+  def collection_path
+    self.class.collection_path
+  end
+
+  def variables
+    super.transform_values do |details|
+      if details['type'] == 'Json'
+        JSON.parse(details['value'])
+      else
+        details['value']
+      end
+    end
+  end
+
+  def queue_task
+    task_class.perform_later(id, variables)
+  end
+
+  def run_now
+    task_class_name.safe_constantize.perform_now id, variables
+  end
+
+  def self.fetch_and_lock(topics, lock_duration: nil, long_polling_duration: nil)
+    long_polling_duration ||= long_polling_duration()
+    lock_duration ||= lock_duration()
+    topic_details = Array(topics).map do |topic|
+      { topicName: topic, lockDuration: lock_duration }
+    end
+    fetchAndLock workerId: worker_id, maxTasks: max_polling_tasks, asyncResponseTimeout: long_polling_duration,
+                 topics: topic_details
+  end
+
+  def task_class_name
+    "#{process_definition_key}::#{activity_id}"
+  end
+
+  def task_class
+    task_class_name.safe_constantize.tap do |klass|
+      raise Camunda::MissingImplementationClass, task_class_name unless klass
+    end
+  end
+end