bas 1.8.0 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a27720481a463c1a4a6edaeda8d9c159d009a11546802f559fd4232be721a146
-  data.tar.gz: fb829e6b146c295403118870324641d6e8e57ca3231259493aa686c4045d2b80
+  metadata.gz: fe416744cd3c3fb9f0902dfc6a3b1432b63425a00da2cea4828a69b0f7e4595a
+  data.tar.gz: 02701d0e8b83c71e0721ebae2a197c6f9204414d3a6f313052152bc2e6957863
 SHA512:
-  metadata.gz: 8a76d3b14aaf04f243a26968e79726025156d491f47ecde2435b5f83c316d3275a61f5cda1de54105459e0d420678c5379194d59f7c7e3d21c8208c10305c730
-  data.tar.gz: 34d41b30c0b3520edd259d325973b6b6a87467f7aac874ee17b630a292b68c57155c40157748a8a5c37c593e93be68dd9cee94136b55155d30324a6744a3d2db
+  metadata.gz: b63e685728abb1a3c80ab896aca20f9621a08b3f3defa9ca682912e9722359a3510b2bfd65154bedc3a0171f372ea9f1df63ae6305bbfc48b28f36477c8c2761
+  data.tar.gz: 7f73e57bc600b044a82deb51c97b30eab54bc5de48122f554d18614e08a273950fa705f5403accd6ff5899e54dbba5ccb3634cf0504769073a55d8d6a7b695bc

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+# 1.9.0 (15.07.2025)
+- [feat: Implement client to perform process deployments and instance creation in Operaton via the REST API](https://github.com/kommitters/bas/pull/146)
+
+# 1.8.1 (08.07.2025)
+- [refactor: Refactor client for correct use of shared_storage](https://github.com/kommitters/bas/pull/144)
+
 # 1.8.0 (07.07.2025)
 - [Feat: Implement client to interact with Operaton's API-REST](https://github.com/kommitters/bas/pull/142)
 

data/lib/bas/utils/operaton/base_operaton_client.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module Utils
+  module Operaton
+    ##
+    # BaseClient provides common HTTP methods and variable formatting logic
+    # shared by all Operaton API clients.
+    #
+    class BaseClient
+      def initialize(base_url:)
+        raise ArgumentError, "base_url is required" if base_url.to_s.strip.empty?
+
+        @base_url = base_url.chomp("/")
+        @conn = build_conn
+      end
+
+      private
+
+      def build_conn
+        # Override to add multipart support for file uploads and URL encoding for form data
+        Faraday.new(url: @base_url) do |f|
+          f.request :json
+          f.response :json, content_type: /\bjson$/
+          f.adapter Faraday.default_adapter
+          f.options.timeout = 30
+          f.options.open_timeout = 10
+        end
+      end
+
+      def full_url(path)
+        "#{@base_url}#{path.start_with?("/") ? path : "/#{path}"}"
+      end
+
+      def get(path, params = {})
+        response = @conn.get(full_url(path), params)
+        handle_response(response)
+      end
+
+      def post(path, body = {}, headers = {})
+        response = @conn.post(full_url(path)) do |req|
+          req.headers.update(headers) if headers.any?
+          req.body = body
+        end
+        handle_response(response)
+      end
+
+      def handle_response(response)
+        unless response.success?
+          error_body = response.body.is_a?(Hash) ? response.body : { message: response.body }
+          raise "Operaton API Error #{response.status}: #{error_body["message"] || error_body}"
+        end
+
+        response.body
+      end
+
+      def format_variables(vars)
+        vars.transform_values do |value|
+          {
+            value: value,
+            type: ruby_type_to_operaton_type(value)
+          }
+        end
+      end
+
+      def ruby_type_to_operaton_type(value)
+        case value
+        when nil then "Null"
+        when String then "String"
+        when Integer then "Integer"
+        when Float then "Double"
+        when TrueClass, FalseClass then "Boolean"
+        when Array, Hash then "Json"
+        else "Object"
+        end
+      end
+    end
+  end
+end

data/lib/bas/utils/operaton/external_task_client.rb

@@ -2,114 +2,88 @@
 
 require "faraday"
 require "json"
+require_relative "base_operaton_client"
+
+module Utils
+  module Operaton
+    ##
+    # Client for interacting with Operaton's External Task API.
+    #
+    # This client provides methods to manage external task lifecycle including:
+    # - Fetching and locking tasks
+    # - Completing tasks with variables
+    # - Unlocking tasks
+    # - Reporting task failures
+    #
+    # @example
+    #   client = Utils::Operaton::ExternalTaskClient.new(base_url: "https://api.operaton.com", worker_id: "worker-123")
+    #   tasks = client.fetch_and_lock("my-topic")
+    #
+    class ExternalTaskClient < BaseClient
+      def initialize(params)
+        @worker_id = params[:worker_id]
+        validate_params!(params)
+        super(base_url: params[:base_url])
+      end
 
-module Bas
-  module Utils
-    module Operaton
-      # Client for interacting with Operaton's External Task API
-      #
-      # This client provides methods to manage external task lifecycle including:
-      # - Fetching and locking tasks
-      # - Completing tasks with variables
-      # - Unlocking tasks
-      # - Reporting task failures
-      #
-      # @example
-      #   client = ExternalTaskClient.new(base_url: "https://api.operaton.com", worker_id: "worker-123")
-      #   tasks = client.fetch_and_lock("my-topic")
-      class ExternalTaskClient
-        def initialize(base_url:, worker_id:)
-          raise ArgumentError, "base_url cannot be nil or empty" if base_url.nil? || base_url.empty?
-          raise ArgumentError, "worker_id cannot be nil or empty" if worker_id.nil? || worker_id.empty?
-
-          @base_url = base_url
-          @worker_id = worker_id
-
-          @conn = Faraday.new(url: base_url) do |f|
-            f.request :json
-            f.response :json, content_type: /\bjson$/
-            f.adapter Faraday.default_adapter
-          end
-        end
-
-        def fetch_and_lock(topics_str, lock_duration: 10_000, max_tasks: 1, use_priority: true, variables: [])
-          post("/external-task/fetchAndLock",
-               workerId: @worker_id,
-               maxTasks: max_tasks,
-               usePriority: use_priority,
-               topics: build_topics_payload(topics_str, lock_duration, variables))
-        end
-
-        def complete(task_id, variables = {})
-          post("/external-task/#{task_id}/complete", workerId: @worker_id,
-                                                     variables: format_variables(variables))
-        end
-
-        def get_variables(task_id)
-          get("/external-task/#{task_id}/variables")
-        end
-
-        def unlock(task_id)
-          post("/external-task/#{task_id}/unlock")
-        end
-
-        def report_failure(task_id, error_message:, error_details:, retries:, retry_timeout:)
-          post("/external-task/#{task_id}/failure",
-               workerId: @worker_id,
-               errorMessage: error_message,
-               errorDetails: error_details,
-               retries: retries,
-               retryTimeout: retry_timeout)
-        end
-
-        private
-
-        def build_topics_payload(topics_str, lock_duration, variables)
-          topic_names = topics_str.is_a?(Array) ? topics_str : topics_str.to_s.split(",")
-          topic_names.map do |name|
-            {
-              topicName: name.strip,
-              lockDuration: lock_duration,
-              variables: variables
-            }
-          end
-        end
+      def fetch_and_lock(topics_str, lock_duration: 10_000, max_tasks: 1, use_priority: true, variables: [])
+        post(
+          "/external-task/fetchAndLock",
+          {
+            workerId: @worker_id,
+            maxTasks: max_tasks,
+            usePriority: use_priority,
+            topics: build_topics_payload(topics_str, lock_duration, variables)
+          }
+        )
+      end
 
-        def full_url(path)
-          "#{@base_url}#{path}"
-        end
+      def complete(task_id, variables = {})
+        post(
+          "/external-task/#{task_id}/complete",
+          {
+            workerId: @worker_id,
+            variables: format_variables(variables)
+          }
+        )
+      end
 
-        def post(path, body = {})
-          handle_response(@conn.post(full_url(path), body))
-        end
+      def get_variables(task_id)
+        get("/external-task/#{task_id}/variables")
+      end
 
-        def get(path, params = {})
-          handle_response(@conn.get(full_url(path), params))
-        end
+      def unlock(task_id)
+        post("/external-task/#{task_id}/unlock")
+      end
 
-        def handle_response(response)
-          raise "Operaton API Error #{response.status}: #{response.body}" unless response.success?
+      def report_failure(task_id, error_message:, error_details:, retries:, retry_timeout:)
+        post(
+          "/external-task/#{task_id}/failure",
+          {
+            workerId: @worker_id,
+            errorMessage: error_message,
+            errorDetails: error_details,
+            retries: retries,
+            retryTimeout: retry_timeout
+          }
+        )
+      end
 
-          response.body
-        end
+      private
 
-        def format_variables(vars)
-          vars.transform_values do |value|
-            {
-              value: value,
-              type: ruby_type_to_operaton_type(value)
-            }
-          end
-        end
+      def validate_params!(params)
+        raise ArgumentError, "base_url cannot be nil or empty" if params[:base_url].to_s.strip.empty?
+        raise ArgumentError, "worker_id cannot be nil or empty" if params[:worker_id].to_s.strip.empty?
+      end
 
-        def ruby_type_to_operaton_type(value)
-          case value
-          when String then "String"
-          when Integer then "Integer"
-          when Float then "Double"
-          when TrueClass, FalseClass then "Boolean"
-          else "Object"
-          end
+      def build_topics_payload(topics_str, lock_duration, variables)
+        topic_names = topics_str.is_a?(Array) ? topics_str : topics_str.to_s.split(",")
+        topic_names.map do |name|
+          {
+            topicName: name.strip,
+            lockDuration: lock_duration,
+            variables: variables
+          }
         end
       end
     end

data/lib/bas/utils/operaton/process_client.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require "faraday/multipart"
+require "logger"
+require_relative "base_operaton_client"
+
+module Utils
+  module Operaton
+    ##
+    # Client for deploying BPMN processes and starting process instances in Operaton (Camunda 7 API compatible)
+    #
+    # @example
+    #   client = Utils::Operaton::ProcessClient.new(base_url: "https://api.operaton.com")
+    #   tasks = client.deploy_process(file_path, deployment_name: deployment_name)
+    #
+    class ProcessClient < BaseClient
+      def initialize(base_url:)
+        @logger = defined?(Rails) ? Rails.logger : Logger.new($stdout)
+        super(base_url: base_url)
+      end
+
+      def deploy_process(file_path, deployment_name:)
+        raise "File not found: #{file_path}" unless File.exist?(file_path)
+        raise "File is not readable: #{file_path}" unless File.readable?(file_path)
+
+        @logger.info "📁 Attempting to read file: #{file_path}"
+        @logger.info "📦 Deployment name: #{deployment_name}"
+
+        payload = {
+          "deployment-name" => deployment_name,
+          "deploy-changed-only" => "true",
+          "data" => Faraday::Multipart::FilePart.new(file_path, "application/octet-stream", File.basename(file_path))
+        }
+
+        post("/deployment/create", payload)
+      end
+
+      def instance_with_business_key_exists?(process_key, business_key)
+        query_params = {
+          processDefinitionKey: process_key,
+          maxResults: 50
+        }
+
+        response = get("/history/process-instance", query_params)
+        response.any? { |instance| instance["businessKey"] == business_key }
+      end
+
+      def start_process_instance_by_key(process_key, business_key:, variables: {}, validate_business_key: true)
+        validate_uniqueness!(process_key, business_key) if validate_business_key
+
+        json_payload = {
+          businessKey: business_key,
+          variables: format_variables(variables)
+        }
+
+        post(
+          "/process-definition/key/#{process_key}/start",
+          JSON.generate(json_payload),
+          { "Content-Type" => "application/json" }
+        )
+      end
+
+      private
+
+      def build_conn
+        Faraday.new(url: @base_url) do |f|
+          f.request :multipart
+          f.request :url_encoded
+          f.response :json, content_type: /\bjson$/
+          f.adapter Faraday.default_adapter
+        end
+      end
+
+      def validate_uniqueness!(process_key, business_key)
+        return unless instance_with_business_key_exists?(process_key, business_key)
+
+        raise "There is already an instance for processing '#{process_key}' with business key '#{business_key}'"
+      end
+    end
+  end
+end

data/lib/bas/version.rb

@@ -2,5 +2,5 @@
 
 module Bas
   # Gem version
-  VERSION = "1.8.0"
+  VERSION = "1.9.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bas
 version: !ruby/object:Gem::Version
-  version: 1.8.0
+  version: 1.9.0
 platform: ruby
 authors:
 - kommitters Open Source
@@ -23,6 +23,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-multipart
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: httparty
   requirement: !ruby/object:Gem::Requirement
@@ -98,7 +112,9 @@ files:
 - lib/bas/utils/notion/update_db_page.rb
 - lib/bas/utils/notion/update_db_state.rb
 - lib/bas/utils/openai/run_assistant.rb
+- lib/bas/utils/operaton/base_operaton_client.rb
 - lib/bas/utils/operaton/external_task_client.rb
+- lib/bas/utils/operaton/process_client.rb
 - lib/bas/utils/postgres/request.rb
 - lib/bas/version.rb
 - renovate.json