camunda-workflow 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 258061e8801a974e302c84e184e90c60771aea045ac8ac51bd92afdcbfc4acc9
-  data.tar.gz: 9aa801c96ff96951ce08f7ed35d69d36772b9122aa4ac51addf62979ad7b63d5
+  metadata.gz: ba961748beb590604ec47e0044a1ce7fa50f97d45bec52652a0e528011e4b2f3
+  data.tar.gz: 3886388d63f770a0fa49686489cbb5a82e3884df697d52cbb9c28582ac5dd867
 SHA512:
-  metadata.gz: 8e77b9f038bad10d3e3606a4dc9ee3e594c050006dcaa0018733f41fc3f37d13db6392d3e76b15e1b88362b6623433e8495e664fa294e9197db849da7d71598e
-  data.tar.gz: 3769a359d104c320094b44a33b4145caa7d36cf4b96b5054d6df452325973ea0ec4efc3903ef180488bf112e90c3840fa94ca95f72ca2db97ac515a646d7e546
+  metadata.gz: fc768ad2478ce728101e69d6c891e53e0045a0ea266a0c2d87d87109f0692cc9d7b3c554f4048c261d96d06e23c3c4f2b66a1054ceeb8f8804bcf3de1748bc05
+  data.tar.gz: de9541842d8c4158a7bf7553a527ffd25a67fdd7dfb6d1b1da8fa5fe713cb58f01c41f0f2dc1d91984b903aae95d77c91b98ea1120661fcb2dd1d37109ec2420

data/CHANGELOG.md

@@ -1,15 +1,44 @@
 # Changelog
 
-## [Unreleased](https://github.com/amalagaura/camunda-workflow/tree/HEAD)
+## [v0.1.4](https://github.com/amalagaura/camunda-workflow/tree/v0.1.4) (2019-12-11)
 
-[Full Changelog](https://github.com/amalagaura/camunda-workflow/compare/fc9ab266909628118a892082abdff953f3bc7eca...HEAD)
+[Full Changelog](https://github.com/amalagaura/camunda-workflow/compare/v0.1.3...v0.1.4)
+
+**Closed issues:**
+
+- add find\_by! [\#13](https://github.com/amalagaura/camunda-workflow/issues/13)
 
 **Merged pull requests:**
 
+- Add find\_by! to all Camunda Her models [\#14](https://github.com/amalagaura/camunda-workflow/pull/14) ([amalagaura](https://github.com/amalagaura))
+- Yarddoc documentation [\#12](https://github.com/amalagaura/camunda-workflow/pull/12) ([curatingbits](https://github.com/curatingbits))
+
+## [v0.1.3](https://github.com/amalagaura/camunda-workflow/tree/v0.1.3) (2019-12-06)
+
+[Full Changelog](https://github.com/amalagaura/camunda-workflow/compare/v0.1.2...v0.1.3)
+
+**Closed issues:**
+
+- When there is a logic error in submitting a user task we are getting a MissingTask error instead [\#9](https://github.com/amalagaura/camunda-workflow/issues/9)
+- If a class does not exist, the Poller loop crashes [\#7](https://github.com/amalagaura/camunda-workflow/issues/7)
+
+**Merged pull requests:**
+
+- Raise Submission errors if Camunda does not accept completion [\#11](https://github.com/amalagaura/camunda-workflow/pull/11) ([amalagaura](https://github.com/amalagaura))
+- Allow Poller to not exit its loop when there is a missing class and report error [\#8](https://github.com/amalagaura/camunda-workflow/pull/8) ([amalagaura](https://github.com/amalagaura))
+
+## [v0.1.2](https://github.com/amalagaura/camunda-workflow/tree/v0.1.2) (2019-11-27)
+
+[Full Changelog](https://github.com/amalagaura/camunda-workflow/compare/fc9ab266909628118a892082abdff953f3bc7eca...v0.1.2)
+
+**Merged pull requests:**
+
+- Add rubocop rspec [\#6](https://github.com/amalagaura/camunda-workflow/pull/6) ([amalagaura](https://github.com/amalagaura))
 - Correct find\_by\_business\_key\_and\_task\_definition\_key! [\#5](https://github.com/amalagaura/camunda-workflow/pull/5) ([amalagaura](https://github.com/amalagaura))
-- added authentication via templates for spring\_boot generator and Her [\#4](https://github.com/amalagaura/camunda-workflow/pull/4) ([curatingbits](https://github.com/curatingbits))
+- added authentication via templates for spring\\_boot generator and Her [\#4](https://github.com/amalagaura/camunda-workflow/pull/4) ([curatingbits](https://github.com/curatingbits))
 - Refactor to return proper Her models after responses [\#3](https://github.com/amalagaura/camunda-workflow/pull/3) ([amalagaura](https://github.com/amalagaura))
 - Added tests for Camunda workflow [\#2](https://github.com/amalagaura/camunda-workflow/pull/2) ([curatingbits](https://github.com/curatingbits))
 
 
+
 \* *This Changelog was automatically generated by [github_changelog_generator](https://github.com/github-changelog-generator/github-changelog-generator)*

data/lib/camunda.rb

@@ -3,19 +3,25 @@ require 'active_support/core_ext/object/blank.rb'
 require 'her'
 require 'faraday'
 require 'faraday_middleware'
-
+# Top level module for camunda-workflow.
 module Camunda
+  # Camunda class
   class << self
+    # Allows setting the logger to a custom logger
     attr_writer :logger
-
+    # Default is output to the standard output stream.
+    # @return [Object] instance which is used for logging
     def logger
       @logger ||= Logger.new($stdout).tap do |log|
         log.progname = name
       end
     end
   end
-
+  ##
+  # Responsible for handling deserialization of variables.
   class Her::Middleware::SnakeCase < Faraday::Response::Middleware
+    # Check if variables are an Array or JSON and ensure variable names are transformed back from camelCase to snake_case.
+    # @param env [Array,Hash]
     def on_complete(env)
       return if env[:body].blank?
 
@@ -28,23 +34,35 @@ module Camunda
       env[:body] = JSON.generate(json)
     end
 
+    private
+
+    # Return a new hash with all keys converted by the block operation.
     def transform_hash!(hash)
       hash.deep_transform_keys!(&:underscore)
     end
   end
-
+  # Error when class corresponding to Camunda bpmn task does not exist.
   class MissingImplementationClass < StandardError
+    # Initializes message for MissingImplementationClass
     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
-
+  # Error when deployment of process definition fails.
   class ProcessEngineException < StandardError
   end
-
+  # Error when BPMN process cannot be deployed.
   class BpmnError < StandardError
-    attr_reader :error_code, :variables
+    # Camunda BPMN error code
+    # @return [String]
+    attr_reader :error_code
+    # variables to send to Camunda along with the error
+    # @return [Hash]
+    attr_reader :variables
 
+    # @param message [String]
+    # @param error_code [String]
+    # @param variables [Hash]
     def initialize(message:, error_code:, variables: {})
       super(message)
       @error_code = error_code

data/lib/camunda/bpmn_xml.rb

@@ -1,50 +1,71 @@
+# Used to parse bpmn file during bpmn_classes generator to create Camunda job class based on process id
 class Camunda::BpmnXML
-  attr_reader :doc
+  # @param io_or_string [IO,String] valid xml string for bpmn file
   def initialize(io_or_string)
     @doc = Nokogiri::XML(io_or_string)
   end
 
+  # Friendly name of this BPMN file is the module name
+  # @return [String] module name
   def to_s
     module_name
   end
 
+  # @return [String] Id (process definition key) of the BPMN process
+  # @example
+  #   "CamundaWorkflow"
   def module_name
     @doc.xpath('/bpmn:definitions/bpmn:process').first['id']
   end
 
+  # creates a new instance of Camunda::BpmnXML::Task
   def external_tasks
     @doc.xpath('//*[@camunda:type="external"]').map do |task|
       Task.new(task)
     end
   end
 
+  # We may have tasks with different topics. Returns classes with topics which are the same as the BPMN process id
+  # @return [Array<String>] class names which should be implemented
+  # @example
+  #   ["DoSomething"]
   def class_names_with_same_bpmn_id_as_topic
     tasks_with_same_bpmn_id_as_topic.map(&:class_name)
   end
 
+  # @return [Array<String>] array of modularized class names
+  # @example
+  #   ["CamundaWorkflow::DoSomething"]
   def modularized_class_names
     class_names_with_same_bpmn_id_as_topic.map { |name| "#{module_name}::#{name}" }
   end
 
+  # @return [Array<String>] topics in this BPMN file
   def topics
     @doc.xpath('//*[@camunda:topic]').map { |node| node.attribute('topic').value }.uniq
   end
 
   private
 
+  # We may have tasks with different topics.
+  # @return [Array<Camunda::BpmnXML::Task>] tasks with topics which are the same as the BPMN process id
   def tasks_with_same_bpmn_id_as_topic
     external_tasks.select { |task| task.topic == module_name }
   end
 
+  # Wrapper for BPMN task XML node
   class Task
+    # Stores XML node about a task
     def initialize(task)
       @task = task
     end
 
+    # Extracts class name from Task XML node
     def class_name
       @task.attribute('id').value
     end
 
+    # Extracts topic name from Task XML node
     def topic
       @task.attribute('topic').value
     end

data/lib/camunda/deployment.rb

@@ -1,6 +1,21 @@
+# Deployment is responsible for creating BPMN, DMN, and CMMN processes within Camunda. Before a process (or case, or decision)
+# can be executed by the process engine, it has to be deployed. A deployment is a logical entity that groups multiple resources
+# that are deployed together. Camunda offers an application called Modeler(https://camunda.com/download/modeler/) that allows you
+# to create and edit BPMN diagrams and BPMN decision tables.
+# @see https://docs.camunda.org/manual/7.4/user-guide/process-engine/deployments/
+# @note You must supply the paths of the BPMN files as a param titled file_names to deploy the BPMN file
+# and deploy BPMN, DMN, CMMN definitions in the Camunda engine.
 class Camunda::Deployment < Camunda::Model
   collection_path 'deployment'
-  # Only supporting .create which uses a POST on deployment/create.
+  # Deploys a new process definition to Camunda and returns an instance of Camunda::ProcessDefinition.
+  # @note Only supporting .create which uses a POST on deployment/create.
+  # @example
+  #   pd = Camunda::Deployment.create(file_names: ['bpmn/diagrams/sample.bpmn']).first
+  # @param files_names [Array<String>] file paths of the bpmn file for deployment
+  # @param tenant_id [String] supplied when a single Camunda installation should serve more than one tenant
+  # @param deployment_source [String] the source of where the deployment occurred.
+  # @param deployment_name [String] provide the name of the deployment, otherwise the deployment name will be the bpmn file names.
+  # @return [Camunda::ProcessDefinition]
   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
@@ -11,12 +26,18 @@ class Camunda::Deployment < Camunda::Model
     deployed_process_definitions(response[:parsed_data][:data][:deployed_process_definitions])
   end
 
+  # Convenience method for dealing with files and IO that are to be uploaded
+  # @param file_names [Array<String>] local files paths to be uploaded
   def self.file_data(file_names)
     file_names.map do |file_name|
       [file_name, UploadIO.new(file_name, 'text/plain')]
     end.to_h
   end
 
+  # Returns a new instance of Camunda::ProcessDefinition according to definitions hash returned by Camunda
+  # @raise [ProcessEngineException] if process definition is nil
+  # @param definitions_hash [Hash]
+  # @return [Array<Camunda::ProcessDefinition>]
   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,

data/lib/camunda/external_task.rb

@@ -1,22 +1,42 @@
 require 'active_support/core_ext/string/inflections.rb'
-
+# External Tasks are the task entity for camunda. We can query the topic and lock the task. After the task
+# is locked, the external task of the process instance can be worked and completed. Below is an excerpt from the Camunda
+# documentation regarding the ExternalTask process.
+# @see https://docs.camunda.org/manual/7.7/user-guide/process-engine/external-tasks/
+# "When the process engine encounters a service task that is configured to be externally handled, it creates an external task
+# instance and adds it to a list of external tasks(step 1). The task instance receives a topic that identifies the nature of
+# the work to be performed. At a time in the future, an external worker may fetch and lock tasks for a specific set of
+# topics (step 2). To prevent one task being fetched by multiple workers at the same time, a task has a timestamp-based lock
+# that is set when the task is acquired. Only when the lock expires, another worker can fetch the task again. When an external
+# worker has completed the desired work, it can signal the process engine to continue process execution after the service
+# task (step 3)."
 class Camunda::ExternalTask < Camunda::Model
+  # Camunda engine doesn't searching on snake_case variables.
   include Camunda::VariableSerialization
+  # collection_path sets the path for Her in Camunda::Model
   collection_path 'external-task'
   custom_post :fetchAndLock, :unlock
 
+  # @note long_polling_duration is defaulted to 30 seconds in Camunda::Workflow.configuration.
+  # @return [Integer] default polling duration from Camunda::Workflow configuration
   def self.long_polling_duration
     Camunda::Workflow.configuration.long_polling_duration.in_milliseconds
   end
 
+  # @note Max polling tasks is defaulted to 2 in Camunda::Workflow.configuration.
+  # @return [Integer] sets the max polling tasks
   def self.max_polling_tasks
     Camunda::Workflow.configuration.max_polling_tasks
   end
 
+  # Default lock duration time is set to 14 days in Camunda::Workflow.configuration.
+  # @return [Integer] default lock duration time
   def self.lock_duration
     Camunda::Workflow.configuration.lock_duration.in_milliseconds
   end
 
+  # Reports a failure to Camunda process definition and creates an incident for a process instance.
+  # @param input_variables [Hash] process variables
   def failure(exception, input_variables={})
     variables_information = "Input variables are #{input_variables.inspect}\n\n" if input_variables.present?
     self.class.post_raw("#{collection_path}/#{id}/failure",
@@ -24,12 +44,17 @@ class Camunda::ExternalTask < Camunda::Model
                         errorDetails: variables_information.to_s + exception.full_message)[:response]
   end
 
+  # Reports the error to Camunda and creates an incident for the process instance.
+  # @param bpmn_exception [Camunda::BpmnError]
   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
 
+  # Completes the process instance of a fetched task
+  # @param variables [Hash] submitted when starting the process definition
+  # @raise [Camunda::ExternalTask::SubmissionError] if Camunda does not accept the task submission
   def complete(variables={})
     self.class.post_raw("#{collection_path}/#{id}/complete",
                         workerId: worker_id, variables: serialize_variables(variables))[:response]
@@ -38,14 +63,20 @@ class Camunda::ExternalTask < Camunda::Model
     end
   end
 
+  # Returns the worker id for an external task
+  # @note default is set to '0' in Camunda::Workflow.configuration
+  # @return [String]
   def worker_id
     self.class.worker_id
   end
 
+  # Helper method for instances since collection_path is a class method
+  # @return [String]
   def collection_path
     self.class.collection_path
   end
 
+  # deserializes JSON attributes from variables returned by Camunda API
   def variables
     super.transform_values do |details|
       if details['type'] == 'Json'
@@ -56,14 +87,39 @@ class Camunda::ExternalTask < Camunda::Model
     end
   end
 
+  # Queues the task to run at a specific time via ActiveJob
+  # @example
+  #   # Below will retrieve current running process instances with the definition key "CamundaWorkflow"
+  #   # and queues the instances to be run at a specific time.
+  #   task = Camunda::ExternalTask.fetch_and_lock("CamundaWorkflow")
+  #   task.each(&:queue_task)
+  # @return [Camunda::ExternalTask]
   def queue_task
     task_class.perform_later(id, variables)
   end
 
+  # Runs the task using ActiveJob based on the classes created by bpmn_classes_generator. Before an external task
+  # can be run, you must #fetch_and_lock the task.
+  # @see fetch_and_lock
+  # @example
+  #   # Below will retrieve current running process instances with the definition key "CamundaWorkflow"
+  #   # and run the instances.
+  #   task = Camunda::ExternalTask.fetch_and_lock("CamundaWorkflow")
+  #   task.each(&:run_now)
+  # @return [Camunda::ExternalTask]
   def run_now
     task_class_name.safe_constantize.perform_now id, variables
   end
 
+  # Locking means that the task is reserved for this worker for a certain duration beginning with the time of fetching and
+  # prevents that another worker can fetch the same task while the lock is valid. Locking duration is set in the the
+  # Camunda::Workflow configuration. Before an external task can be completed, it must be locked.
+  # @example
+  #   task = Camunda::ExternalTask.fetch_and_lock("CamundaWorkflow")
+  # @param topics [Array<String>] definition keys
+  # @param lock_duration [Integer]
+  # @param long_polling_duration [Integer]
+  # @return [Camunda::ExternalTask]
   def self.fetch_and_lock(topics, lock_duration: nil, long_polling_duration: nil)
     long_polling_duration ||= long_polling_duration()
     lock_duration ||= lock_duration()
@@ -74,16 +130,22 @@ class Camunda::ExternalTask < Camunda::Model
                  topics: topic_details
   end
 
+  # Returns the class name which is supposed to implement this task
+  # @return [String] modularized class name of bpmn task implementation
   def task_class_name
     "#{process_definition_key}::#{activity_id}"
   end
 
+  # Checks to make sure an implementation class is available
+  # @return [Module] return class name
+  # @raise [Camunda::MissingImplementationClass] if the class does not exist
   def task_class
     task_class_name.safe_constantize.tap do |klass|
       raise Camunda::MissingImplementationClass, task_class_name unless klass
     end
   end
-
+  # If the BPMN file expects a variable and the variable isn't supplied with an SubmissionError will be raised
+  # indicating that the variable does not exist.
   class SubmissionError < StandardError
   end
 end

data/lib/camunda/external_task_job.rb

@@ -1,4 +1,16 @@
+# Camunda::ExternalTaskJob module is included in the generated bpmn_classes for ActiveJob and handles
+# the task completion or failure for a given worker that has been locked to be performed.
+# @see Camunda::ExternalTask
 module Camunda::ExternalTaskJob
+  # Performs the external task for the process definition and processes completion or throws an error. The below example
+  # shows how to run a task based off of our generated classes from the bpmn_classes generator from the sample.bpmn file
+  # provided.
+  # @example
+  #   task = Camunda::ExternalTask.fetch_and_lock('CamundaWorkflow').first
+  #   CamundaWorkflow::DoSomething.new.perform(task.id, x: 'abcd')
+  # @param id [Integer] of the worker for the locked task
+  # @param input_variables [Hash]
+  # @raise [Camunda::ExternalTask::SubmissionError] if Camunda does not accept the submission of the task
   def perform(id, input_variables)
     output_variables = bpmn_perform(input_variables)
     output_variables = {} if output_variables.nil?
@@ -14,24 +26,35 @@ module Camunda::ExternalTaskJob
     report_failure id, e, input_variables
   end
 
+  # Reports completion for an external task with output variable set in bpmn_perform.
+  # @param id [Integer] of the worker
+  # @param variables [Hash] output variables declared in bpmn_perform
   def report_completion(id, variables)
     # Submit to Camunda using
     # POST /external-task/{id}/complete
     Camunda::ExternalTask.new(id: id).complete(variables)
   end
 
+  # Reports external task failure to the Camunda process definition and creates an incident report
+  # @param id [Integer] of the worker for the process instance
+  # @param exception [Object] the exception for the failed task
+  # @param input_variables [Hash] given to the process definition
   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
 
+  # Reports an error if there is a problem with bpmn_perform
+  # @param id [Integer] of the process instance
+  # @param exception [Camunda::BpmnError] instance of Camunda::BpmnError
   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
 
+  # Default bpmn_perform which raises an error. Forces user to create their own implementation
   def bpmn_perform(_variables)
     raise StandardError, "Please define this method which takes a hash of variables and returns a hash of variables"
   end

data/lib/camunda/incident.rb

@@ -1,3 +1,6 @@
+# Allows for incidents to be reported to Camunda. Incidents are notable events
+# that happen in the process engine. Such incidents usually indicate some kind of problem
+# related to process execution. Incidents are reported on failures that occur.
 class Camunda::Incident < Camunda::Model
   collection_path 'incident'
 end

data/lib/camunda/matchers.rb

@@ -1,8 +1,9 @@
+# RSpec matcher for topic names used for testing bpmn files
 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 matcher used for testing bpmn files
 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}" }

data/lib/camunda/model.rb

@@ -1,8 +1,11 @@
 require 'her/model'
+# This class in the main element of Her. It defines which API models will be bound to.
 class Camunda::Model
   include Her::Model
 
+  # We use a lambda so that this is evaluated after Camunda::Workflow.configuration is set
   api = lambda do
+    # Configuration for Her and Faraday requests and responses
     Her::API.new(url: File.join(Camunda::Workflow.configuration.engine_url)) do |c|
       c.path_prefix = Camunda::Workflow.configuration.engine_route_prefix
       # Request
@@ -22,7 +25,23 @@ class Camunda::Model
 
   use_api api
 
+  # Returns result of find_by but raises an exception instead of returning nil
+  # @param params [Hash] query parameters
+  # @return [Camunda::Model]
+  # @raise [Camunda::Model::RecordNotFound] if query returns no results
+  def self.find_by!(params)
+    find_by(params).tap do |result|
+      raise Camunda::Model::RecordNotFound unless result
+    end
+  end
+
+  # Returns the worker id
+  # @note default worker id is set in Camunda::Workflow.configuration
+  # @return [String] id of worker
   def self.worker_id
     Camunda::Workflow.configuration.worker_id
   end
+
+  class RecordNotFound < StandardError
+  end
 end

data/lib/camunda/poller.rb

@@ -1,4 +1,12 @@
+# The poller will run as an infinite loop with long polling to fetch tasks, queue, and run them.
+# Topic is the process definition key. Below will run the poller to fetch, lock, and run a task for the
+# example process definition with an id of CamundaWorkflow.
+# @example
+#   Camunda::Poller.fetch_and_execute %w[CamundaWorkflow]
 class Camunda::Poller
+  # @param topics [Array] process definition keys
+  # @param lock_duration [Integer] lock duration time, default time is set in Camunda::Workflow.configuration
+  # @param long_polling_duration [Integer] long polling time, default is set to Camunda::Workflow.configuration
   def self.fetch_and_execute(topics, lock_duration: nil, long_polling_duration: nil)
     loop do
       Camunda::ExternalTask

data/lib/camunda/process_definition.rb

@@ -1,7 +1,22 @@
+##
+# A process definition defines the structure of a process. The `key` of a process definition is the logical
+# identifier of the process. It is used throughout the API, most prominently for starting a process instances.
+# The key of a process definition is defined using the `id` property of the corresponding process element in the BPMN XML file.
+# @see https://docs.camunda.org/manual/7.7/user-guide/process-engine/process-engine-concepts/
+# @see Camunda::ProcessInstance
 class Camunda::ProcessDefinition < Camunda::Model
   include Camunda::VariableSerialization
   collection_path 'process-definition'
-
+  # Starts an individual process instance by key and supplies process variables to be included in the process instance. In
+  # the example below a business key is provided. A business key is a domain-specific identifier of a process instance,
+  # it makes querying for task more efficient. The business key is displayed prominently in applications like Camunda Cockpit.
+  # @see https://blog.camunda.com/post/2018/10/business-key/
+  # @example
+  #   pd = Camunda::ProcessDefinition.start_by_key 'CamundaWorkflow', variables: { x: 'abcd' }, businessKey: 'WorkflowBusinessKey'
+  # @param key [String] process definition identifier
+  # @param hash [Hash] sets variables to be included with starting a process definition
+  # @return [Camunda::ProcessInstance]
+  # @raise [Camunda::ProcessEngineException] if submission was unsuccessful
   def self.start_by_key(key, hash={})
     hash[:variables] = serialize_variables(hash[:variables]) if hash[:variables]
     tenant_id = hash.delete(:tenant_id)
@@ -13,6 +28,15 @@ class Camunda::ProcessDefinition < Camunda::Model
     Camunda::ProcessInstance.new response[:parsed_data][:data]
   end
 
+  # Starts an individual process instance for a process definition. The below example shows how to start a process
+  # definition after deployment.
+  # @example
+  #   pd = Camunda::Deployment.create(file_names: ['bpmn/diagrams/sample.bpmn']).first
+  #   pd.start
+  # Starts the process instance by sending a request to the Camunda engine
+  # @param hash [Hash] defaults to {} if no variables are provided
+  # @return [Camunda::ProcessInstance]
+  # @raise [Camunda::ProcessEngineException] if submission was unsuccessful
   def start(hash={})
     hash[:variables] = serialize_variables(hash[:variables]) if hash[:variables]
     response = self.class.post_raw "process-definition/#{id}/start", hash
@@ -21,6 +45,7 @@ class Camunda::ProcessDefinition < Camunda::Model
     Camunda::ProcessInstance.new response[:parsed_data][:data]
   end
 
+  # Sets path to include tenant_id if a tenant_id is provided with a process definition on deployment.
   def self.start_path_for_key(key, tenant_id)
     path = "process-definition/key/#{key}"
     path << "/tenant-id/#{tenant_id}" if tenant_id

data/lib/camunda/process_instance.rb

@@ -1,6 +1,11 @@
+# A process instance is an individual execution of a process definition. The relation of the process instance to the process
+# definition is the same as the relation between Class and Class instance in OOP. When a process definition is started,
+# a process instance is created.
+# @see https://docs.camunda.org/manual/7.4/user-guide/process-engine/process-engine-concepts/
+# @see Camunda::ProcessDefinition
 class Camunda::ProcessInstance < Camunda::Model
   collection_path 'process-instance'
-
+  # GETs the process instance and deserializes the variables
   def variables
     response = self.class.get_raw "process-instance/#{id}/variables"
     deserialize_variables response[:parsed_data][:data]
@@ -8,6 +13,8 @@ class Camunda::ProcessInstance < Camunda::Model
 
   private
 
+  # Deserialize variables and convert variable names from CamelCase to snake_case.
+  # @param hash [Hash] Transforms a hash of Camunda serialized variables to a simple Ruby hash and snake_cases variable names
   def deserialize_variables(hash)
     hash.transform_values do |value_hash|
       case value_hash[:type]

data/lib/camunda/signal.rb

@@ -1,7 +1,14 @@
+##
+# Signal events are events which reference a named signal. Camunda::Signal is used to
+# create a signal with variables.
+# @example
+#    `Camunda::Signal.create name: 'Signal Name', variables: {foo: "bar"}`
 class Camunda::Signal < Camunda::Model
   include Camunda::VariableSerialization
   collection_path 'signal'
-
+  # Creates a signal within the process definition on the Camunda engine
+  # @param hash [Hash] variables that are sent to Camunda engine
+  # @return [{Symbol => Hash,Faraday::Response}]
   def self.create(hash={})
     hash[:variables] = serialize_variables(hash[:variables]) if hash[:variables]
     post_raw collection_path, hash

data/lib/camunda/task.rb

@@ -1,16 +1,33 @@
+# Finds tasks by business key and task definition and allows you to report a task complete and update process variables.
+# If a business key isn't supplied when creating a process definition, you can still retrieve UserTasks by using
+# the `.find_by` helper provided by Her.
+# @see Camunda::ProcessDefinition
+# @see https://github.com/remi/her
+# @example
+#   Camunda::Task.find_by(taskDefinitionKey: 'UserTask')
+# @example
+#   # You can get all tasks with the `.all.each` helper
+#   tasks = Camunda::Task.all.each
+#   # And then complete all tasks like so
+#   tasks.each(&:complete!)
 class Camunda::Task < Camunda::Model
   include Camunda::VariableSerialization
   collection_path 'task'
 
+  # @example
+  #   user_task = Camunda::Task.find_by_business_key_and_task_definition_key!('WorkflowBusinessKey','UserTask')
+  # @param instance_business_key [String] the process instance business key
+  # @param task_key [String] id/key of the user task
+  # @return [Camunda::Task]
   def self.find_by_business_key_and_task_definition_key!(instance_business_key, task_key)
-    find_by(processInstanceBusinessKey: 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
+    find_by!(processInstanceBusinessKey: instance_business_key, taskDefinitionKey: task_key)
   end
 
+  # Complete a task and updates process variables.
+  # @example
+  #   user_task = Camunda::Task.find_by_business_key_and_task_definition_key!('WorkflowBusinessKey','UserTask')
+  #   user_task.complete!
+  # @param vars [Hash] variables to be submitted as part of task completion
   def complete!(vars={})
     self.class.post_raw("#{self.class.collection_path}/#{id}/complete", variables: serialize_variables(vars))[:response]
         .tap do |response|
@@ -18,9 +35,8 @@ class Camunda::Task < Camunda::Model
     end
   end
 
-  class MissingTask < StandardError
-  end
-
+  # Error class when the task cannot be submitted. For instance if the bpmn process expects a variable and the variable
+  # isn't supplied, Camunda will not accept the task
   class SubmissionError < StandardError
   end
 end

data/lib/camunda/variable_serialization.rb

@@ -1,14 +1,21 @@
 require 'active_support/concern'
 module Camunda
+  # The VariableSerialization module adds information to variables so Camunda can parse them. It adds types annotations and
+  # serializes hashes and array to JSON. Camunda engine cannot search on snake_case variables so it changes variable names
+  # to camelCase.
+  # @see Camunda::ProcessDefinition
   module VariableSerialization
     extend ActiveSupport::Concern
-
+    # Wrapper for class level method
     def serialize_variables(variables)
       self.class.serialize_variables(variables)
     end
 
     class_methods do
       # rubocop:disable Metrics/MethodLength
+      # @param variables [Hash]
+      # @return {String,Symbol => {String,Symbol => Object}}
+      # @raise [ArgumentError] if a class instance is passed
       def serialize_variables(variables)
         hash = variables.transform_values do |value|
           case value
@@ -30,6 +37,9 @@ module Camunda
       end
       # rubocop:enable Metrics/MethodLength
 
+      # Transforms keys of a JSON like object (Array,Hash) from snake_case to CamelCase
+      # @param json [Array,Hash]
+      # @return [Hash] returns hash with camelCase keys
       def transform_json(json)
         if json.is_a?(Array)
           json.map { |element| transform_json(element) }

data/lib/camunda/workflow.rb

@@ -1,22 +1,65 @@
 module Camunda
+  ##
+  # Default configuration file for camunda-workflow. These defaults can be overridden using an
+  # initializer file within a Rails application.
+  # @example override default values
+  #   Camunda::Workflow.configure do |config|
+  #     config.engine_url = 'http://localhost:8080'
+  #     config.engine_route_prefix = 'rest'
+  #   end
   module Workflow
+    # Implements Configuration class and sets default instance variables. The default variables can be overridden by creating an
+    # initializer file within your rails application and setting the variables like in the example below.
+    # @note if HTTP Basic Auth is used with the Camunda engine, this is where you would set a camunda_user and camunda_password
+    # using the creditials from a user setup in Camunda Admin.
+    # @example
+    #   'Camunda::Workflow.configure do |config|
+    #     config.engine_url = 'http://localhost:8080'
+    #     config.engine_route_prefix = 'rest'
+    #   end'
     def self.configure
       yield(configuration)
     end
 
+    # Access the Configuration class
+    # @return [Configuration]
     def self.configuration
       @configuration ||= Configuration.new
     end
-
+    # Default instance variables configurations for Her and camunda-workflow
     class Configuration
+      # Sets the deult engine url for Camunda REST Api
+      # @return [String] the url for Camunda deployment
       attr_accessor :engine_url
+      # Engine route prefix that determines the path for the REST Api
+      # Default route for Java spring app is `/rest`
+      # Default route for Camunda deployment is `/rest-engine`
+      # @return [String] the prefix for Camunda REST Api
       attr_accessor :engine_route_prefix
+      # Name of worker, defaults to '0'
+      # @return [String] name of worker
       attr_accessor :worker_id
+      # The default fetch_and_lock time duration when fetching a task
+      # @return [Integer] time in days to lock task
       attr_accessor :lock_duration
+      # Max polling tasks when using the command line to fetch and lock tasks
+      # @return [Integer] default is set to fetch and lock 2 tasks
       attr_accessor :max_polling_tasks
+      # With the aid of log polling, a request is suspended by the server if no external tasks are available.
+      # Long polling significantly reduces the number of request and enables using resources more
+      # efficiently on both the server and client.
+      # @return [Integer]
       attr_accessor :long_polling_duration
+      # The tenant identifier is specified on the deployment and is propagated to all data
+      # that is created from the deployment(e.g. process definitions, process instances, tacks).
+      # @return [String] name for tenant identifier
       attr_accessor :tenant_id
+      # When HTTP Basic Auth is turned on for Camunda, a user needs to be created in Camunda Admin
+      # and set in to be used in the configuration.
+      # @return [String] Camunda user name for HTTP Basic Auth
       attr_accessor :camunda_user
+      # Camunda password is supplied with the Camunda user to authenticate using HTTP Basic Auth.
+      # @return [String] Camunda password for HTTP Basic Auth
       attr_accessor :camunda_password
 
       def initialize

data/lib/camunda/workflow/version.rb

@@ -1,5 +1,5 @@
 module Camunda
   module Workflow
-    VERSION = '0.1.3'.freeze
+    VERSION = '0.1.4'.freeze
   end
 end

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

@@ -1,15 +1,20 @@
 module Camunda
   module Generators
+    # 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.
     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'
 
+      # @return [String] The id of the BPMN process
       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
 
+      # Creates a class name to be used for the task classes created to perform external tasks.
       def validate_class_names
         bpmn_xml.modularized_class_names.each do |class_name|
           validate_constant_name(class_name.demodulize, module_name)
@@ -19,10 +24,13 @@ module Camunda
         puts colorized_class_names.join("\n")
       end
 
+      # Creates module names to be used for the task classes to perform external tasks.
       def create_module
         template 'bpmn_module.rb.template', File.join(model_path, "#{module_name.underscore}.rb")
       end
 
+      # Creates the correct classes from the bpmn file to be used in the provided generator template for the classes
+      # needed to run external tasks.
       def create_classes
         bpmn_xml.class_names_with_same_bpmn_id_as_topic.each do |class_name|
           template 'bpmn_class.rb.template',
@@ -32,6 +40,7 @@ module Camunda
 
       private
 
+      # Validates constant names by attempting to create a Ruby constant
       def validate_constant_name(name, module_name=nil)
         top_level = module_name.nil? ? Module.new : module_name.constantize
         colorized_name = set_color name, :red

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

@@ -1,8 +1,12 @@
 module Camunda
+  # Generator to run and install camunda_job.rb that includes ExternalTaskJob to be used with task classes.
   module Generators
+    # 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
     class InstallGenerator < Rails::Generators::Base
       source_root File.expand_path('templates', __dir__)
-
+      # Copies the camunda_job file to the Rails application.
       def copy_camunda_application_job
         copy_file 'camunda_job.rb', 'app/jobs/camunda_job.rb'
       end

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

@@ -1,3 +1,4 @@
+# All of the BPMN worker classes will inherit from this class
 class CamundaJob < ApplicationJob
   # If using Sidekiq change to include Sidekiq::Worker instead of inheriting from ApplicationJob
   include Camunda::ExternalTaskJob

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

@@ -1,10 +1,13 @@
 module Camunda
   module Generators
+    # 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.
     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'
-
+      # Copys all spring boot files into a rails application and provides a Camunda engine for testing.
       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')
@@ -13,10 +16,12 @@ module Camunda
         copy_file 'Camunda.java', File.join(bpmn_app_path, 'src/main/java/camunda/Camunda.java')
       end
 
+      # Copys a sample bpmn file to help demonstrate the usage for camunda-workflow
       def link_resources_folder
         copy_file 'sample.bpmn', File.join(diagram_path, 'sample.bpmn'), ''
       end
 
+      # Add spring boot files to .gitignore
       def add_to_ignores
         %w[.gitignore .cfignore].each do |file|
           append_to_file file do
@@ -27,6 +32,7 @@ module Camunda
         end
       end
 
+      # Provides instruction regarding an error with EventedFileChecker listening on the entire Rails folder.
       def output_error_instructions
         puts <<~DOC
           If you get an error when starting your Rails app

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: camunda-workflow
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Ankur Sethi