bas 1.8.1 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83923ab43148fb334e5809f95b2c4387b6bffccb36a7b034f9f6067ad9a75783
-  data.tar.gz: 6d78bf8adf6e1644c85fc77c6ff3b60f21953fac861aa1dfc99210422dc84dba
+  metadata.gz: fe416744cd3c3fb9f0902dfc6a3b1432b63425a00da2cea4828a69b0f7e4595a
+  data.tar.gz: 02701d0e8b83c71e0721ebae2a197c6f9204414d3a6f313052152bc2e6957863
 SHA512:
-  metadata.gz: 792b8feddf38fd47f80d1b3443e4a019e2e0fdae196aa02fe6c5949492ffc586abec3a64ba4fcedd0cd53994da2bdaff81008a0d9ffe0c356e7d68650f83b84f
-  data.tar.gz: 73b45576f90b0d47448d78fec58f80ceca36304aa1b52e9c72813c7f102a0cdee71b80d0e1528e8d7f135af618ab2732d48e6e833746b7a46d2824d7a75a8265
+  metadata.gz: b63e685728abb1a3c80ab896aca20f9621a08b3f3defa9ca682912e9722359a3510b2bfd65154bedc3a0171f372ea9f1df63ae6305bbfc48b28f36477c8c2761
+  data.tar.gz: 7f73e57bc600b044a82deb51c97b30eab54bc5de48122f554d18614e08a273950fa705f5403accd6ff5899e54dbba5ccb3634cf0504769073a55d8d6a7b695bc

data/CHANGELOG.md

@@ -1,5 +1,8 @@
 # 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)
 

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,10 +2,12 @@
 
 require "faraday"
 require "json"
+require_relative "base_operaton_client"
 
 module Utils
   module Operaton
-    # Client for interacting with Operaton's External Task API
+    ##
+    # Client for interacting with Operaton's External Task API.
     #
     # This client provides methods to manage external task lifecycle including:
     # - Fetching and locking tasks
@@ -14,42 +16,35 @@ module Utils
     # - Reporting task failures
     #
     # @example
-    #   client = Utils::Operaton::ExternalTaskClient.execute(base_url: "https://api.operaton.com",
-    #                                                        worker_id: "worker-123")
+    #   client = Utils::Operaton::ExternalTaskClient.new(base_url: "https://api.operaton.com", worker_id: "worker-123")
     #   tasks = client.fetch_and_lock("my-topic")
-    class ExternalTaskClient
-      def self.execute(params)
-        new(params)
-      end
-
+    #
+    class ExternalTaskClient < BaseClient
       def initialize(params)
-        validate_params!(params)
-
-        @base_url = params[:base_url]
         @worker_id = params[: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
+        validate_params!(params)
+        super(base_url: params[:base_url])
       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)
+          {
+            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)
+          {
+            workerId: @worker_id,
+            variables: format_variables(variables)
+          }
         )
       end
 
@@ -64,11 +59,13 @@ module Utils
       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
+          {
+            workerId: @worker_id,
+            errorMessage: error_message,
+            errorDetails: error_details,
+            retries: retries,
+            retryTimeout: retry_timeout
+          }
         )
       end
 
@@ -89,43 +86,6 @@ module Utils
           }
         end
       end
-
-      def full_url(path)
-        "#{@base_url}#{path}"
-      end
-
-      def post(path, body = {})
-        handle_response(@conn.post(full_url(path), body))
-      end
-
-      def get(path, params = {})
-        handle_response(@conn.get(full_url(path), params))
-      end
-
-      def handle_response(response)
-        raise "Operaton API Error #{response.status}: #{response.body}" unless response.success?
-
-        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 String then "String"
-        when Integer then "Integer"
-        when Float then "Double"
-        when TrueClass, FalseClass then "Boolean"
-        else "Object"
-        end
-      end
     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.1"
+  VERSION = "1.9.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bas
 version: !ruby/object:Gem::Version
-  version: 1.8.1
+  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