flowable 1.0.0

data/lib/flowable/flowable.rb

@@ -0,0 +1,273 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+require 'base64'
+require 'date'
+
+require_relative 'version'
+
+module Flowable
+  class Error < StandardError; end
+  class NotFoundError < Error; end
+  class UnauthorizedError < Error; end
+  class ForbiddenError < Error; end
+  class BadRequestError < Error; end
+  class ConflictError < Error; end
+
+  class Client
+    CMMN_BASE_PATH = '/flowable-rest/cmmn-api'
+    BPMN_BASE_PATH = '/flowable-rest/service'
+
+    attr_reader :host
+    attr_reader :port
+    attr_reader :username
+    attr_reader :base_path
+    attr_reader :bpmn_base_path
+
+    def initialize(host: 'localhost', port: 8080, username:, password:, base_path: CMMN_BASE_PATH,
+                   bpmn_base_path: BPMN_BASE_PATH, use_ssl: false)
+      @host = host
+      @port = port
+      @username = username
+      @password = password
+      @base_path = base_path
+      @bpmn_base_path = bpmn_base_path
+      @use_ssl = use_ssl
+    end
+
+    # CMMN Resource accessors
+    def deployments
+      @deployments ||= Resources::Deployments.new(self)
+    end
+
+    def case_definitions
+      @case_definitions ||= Resources::CaseDefinitions.new(self)
+    end
+
+    def case_instances
+      @case_instances ||= Resources::CaseInstances.new(self)
+    end
+
+    def tasks
+      @tasks ||= Resources::Tasks.new(self)
+    end
+
+    def plan_item_instances
+      @plan_item_instances ||= Resources::PlanItemInstances.new(self)
+    end
+
+    def history
+      @history ||= Resources::History.new(self)
+    end
+
+    # BPMN Resource accessors
+    def bpmn_deployments
+      @bpmn_deployments ||= Resources::BpmnDeployments.new(self)
+    end
+
+    def process_definitions
+      @process_definitions ||= Resources::ProcessDefinitions.new(self)
+    end
+
+    def process_instances
+      @process_instances ||= Resources::ProcessInstances.new(self)
+    end
+
+    def executions
+      @executions ||= Resources::Executions.new(self)
+    end
+
+    def bpmn_history
+      @bpmn_history ||= Resources::BpmnHistory.new(self)
+    end
+
+    # HTTP methods
+    def get(path, params = {})
+      request(:get, path, params: params)
+    end
+
+    def post(path, body = nil)
+      request(:post, path, body: body)
+    end
+
+    def put(path, body = nil)
+      request(:put, path, body: body)
+    end
+
+    def delete(path, params = {})
+      request(:delete, path, params: params)
+    end
+
+    def post_multipart(path, file_path, additional_fields = {})
+      uri = build_uri(path)
+      boundary = "----Flowable#{rand(1_000_000)}"
+
+      body = build_multipart_body(file_path, additional_fields, boundary)
+
+      http = build_http(uri)
+      request = Net::HTTP::Post.new(uri.request_uri)
+      request['Authorization'] = auth_header
+      request['Content-Type'] = "multipart/form-data; boundary=#{boundary}"
+      request.body = body
+
+      handle_response(http.request(request))
+    end
+
+    private
+
+    def request(method, path, params: {}, body: nil)
+      uri = build_uri(path, params)
+      http = build_http(uri)
+
+      request = build_request(method, uri, body)
+      handle_response(http.request(request))
+    end
+
+    def build_uri(path, params = {})
+      # Determine base path - BPMN resources use service path
+      effective_base_path = path.start_with?('service/') || path.start_with?('repository/') || path.start_with?('runtime/') || (path.start_with?('history/') && !path.include?('cmmn')) ? @bpmn_base_path : @base_path
+
+      # For BPMN paths, strip the 'service/' prefix if present since it's in base path
+      adjusted_path = path.start_with?('service/') ? path.sub('service/', '') : path
+
+      uri = URI::HTTP.build(
+        host: @host,
+        port: @port,
+        path: "#{effective_base_path}/#{adjusted_path}".gsub('//', '/')
+      )
+      uri.query = URI.encode_www_form(params) unless params.empty?
+      uri
+    end
+
+    def build_http(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = @use_ssl
+      http.read_timeout = 30
+      http.open_timeout = 10
+      http
+    end
+
+    def build_request(method, uri, body)
+      request_class = {
+        get: Net::HTTP::Get,
+        post: Net::HTTP::Post,
+        put: Net::HTTP::Put,
+        delete: Net::HTTP::Delete
+      }[method]
+
+      request = request_class.new(uri.request_uri)
+      request['Authorization'] = auth_header
+      request['Accept'] = 'application/json'
+      request['Content-Type'] = 'application/json'
+
+      if body
+        request.body = body.is_a?(String) ? body : body.to_json
+      end
+
+      request
+    end
+
+    def auth_header
+      credentials = Base64.strict_encode64("#{@username}:#{@password}")
+      "Basic #{credentials}"
+    end
+
+    def handle_response(response)
+      case response.code.to_i
+      when 200, 201
+        parse_response(response)
+      when 204
+        true
+      when 400
+        raise BadRequestError, parse_error_message(response)
+      when 401
+        raise UnauthorizedError, 'Invalid credentials'
+      when 404
+        raise NotFoundError, parse_error_message(response)
+      when 409
+        raise ConflictError, parse_error_message(response)
+      else
+        raise Error, "HTTP #{response.code}: #{parse_error_message(response)}"
+      end
+    end
+
+    def parse_response(response)
+      return nil if response.body.nil? || response.body.empty?
+
+      body = response.body
+      content_type = response['Content-Type'] || ''
+
+      # Flowable bug workaround: resourcedata endpoint returns XML with Content-Type: application/json
+      # Check if body starts with XML declaration and return raw body
+      return body if body.start_with?('<?xml')
+
+      if content_type.include?('application/json')
+        # Handle Flowable bug: when Jackson exceeds nesting limit (1000),
+        # it appends an error message to incomplete JSON instead of returning proper error
+        if body.include?('{"message":"Bad request","exception":"Could not write JSON: Document nesting depth')
+          idx = body.index('{"message":"Bad request"')
+          # idx is guaranteed to be non-nil here since we already checked body includes the pattern
+          if idx.positive?
+            # Try to extract valid JSON before the error
+            body = body[0...(idx - 1)]
+          end
+        end
+
+        JSON.parse(body, max_nesting: 1500)
+      else
+        body
+      end
+    end
+
+    def parse_error_message(response)
+      return response.message if response.body.nil? || response.body.empty?
+
+      parsed = JSON.parse(response.body)
+      parsed['errorMessage'] || parsed['message'] || response.body
+    rescue JSON::ParserError
+      response.body
+    end
+
+    def build_multipart_body(file_path, additional_fields, boundary)
+      body = []
+
+      # Add file
+      filename = File.basename(file_path)
+      file_content = File.binread(file_path)
+
+      body << "--#{boundary}"
+      body << "Content-Disposition: form-data; name=\"file\"; filename=\"#{filename}\""
+      body << 'Content-Type: application/octet-stream'
+      body << ''
+      body << file_content
+
+      # Add additional fields
+      additional_fields.each do |name, value|
+        body << "--#{boundary}"
+        body << "Content-Disposition: form-data; name=\"#{name}\""
+        body << ''
+        body << value.to_s
+      end
+
+      body << "--#{boundary}--"
+      body.join("\r\n")
+    end
+  end
+end
+
+# High-level DSL
+require_relative 'resources/base'
+require_relative 'resources/deployments'
+require_relative 'resources/case_definitions'
+require_relative 'resources/case_instances'
+require_relative 'resources/tasks'
+require_relative 'resources/plan_item_instances'
+require_relative 'resources/history'
+require_relative 'resources/bpmn_deployments'
+require_relative 'resources/process_definitions'
+require_relative 'resources/process_instances'
+require_relative 'resources/executions'
+require_relative 'resources/bpmn_history'
+require_relative 'workflow'

data/lib/flowable/resources/base.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Flowable
+  module Resources
+    class Base
+      attr_reader :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      private
+
+      def paginate_params(options)
+        params = {}
+        params[:start] = options[:start] if options[:start]
+        params[:size] = options[:size] if options[:size]
+        params[:sort] = options[:sort] if options[:sort]
+        params[:order] = options[:order] if options[:order]
+        params
+      end
+
+      def build_variables_array(variables)
+        return [] unless variables
+
+        variables.map do |name, value|
+          var = { name: name.to_s, value: value }
+          var[:type] = infer_type(value)
+          var
+        end
+      end
+
+      def infer_type(value)
+        case value
+        when Integer then 'long'
+        when Float then 'double'
+        when TrueClass, FalseClass then 'boolean'
+        when Date, Time, DateTime then 'date'
+        else 'string'
+        end
+      end
+    end
+  end
+end

data/lib/flowable/resources/bpmn_deployments.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Flowable
+  module Resources
+    class BpmnDeployments < Base
+      BASE_PATH = 'service/repository/deployments'
+
+      # List all BPMN deployments
+      # @param options [Hash] Query parameters
+      # @option options [String] :name Filter by exact name
+      # @option options [String] :nameLike Filter by name pattern (use % wildcard)
+      # @option options [String] :category Filter by category
+      # @option options [String] :tenantId Filter by tenant
+      # @option options [Integer] :start Pagination start (default: 0)
+      # @option options [Integer] :size Page size (default: 10)
+      # @option options [String] :sort Sort field (id/name/deployTime/tenantId)
+      # @option options [String] :order Sort order (asc/desc)
+      # @return [Hash] Paginated list of deployments
+      def list(**options)
+        params = paginate_params(options)
+        params[:name] = options[:name] if options[:name]
+        params[:nameLike] = options[:nameLike] if options[:nameLike]
+        params[:category] = options[:category] if options[:category]
+        params[:tenantId] = options[:tenantId] if options[:tenantId]
+        params[:withoutTenantId] = options[:withoutTenantId] if options[:withoutTenantId]
+
+        client.get(BASE_PATH, params)
+      end
+
+      # Get a specific deployment
+      # @param deployment_id [String] The deployment ID
+      # @return [Hash] Deployment details
+      def get(deployment_id)
+        client.get("#{BASE_PATH}/#{deployment_id}")
+      end
+
+      # Create a new deployment from a file
+      # @param file_path [String] Path to BPMN file (.bpmn, .bpmn20.xml, .bar, .zip)
+      # @param name [String] Optional deployment name
+      # @param tenant_id [String] Optional tenant ID
+      # @param category [String] Optional category
+      # @return [Hash] Created deployment
+      def create(file_path, name: nil, tenant_id: nil, category: nil)
+        additional_fields = {}
+        additional_fields[:deploymentName] = name if name
+        additional_fields[:tenantId] = tenant_id if tenant_id
+        additional_fields[:category] = category if category
+
+        client.post_multipart(BASE_PATH, file_path, additional_fields)
+      end
+
+      # Delete a deployment
+      # @param deployment_id [String] The deployment ID
+      # @param cascade [Boolean] Also delete running process instances
+      # @return [Boolean] true if successful
+      def delete(deployment_id, cascade: false)
+        params = {}
+        params[:cascade] = true if cascade
+        client.delete("#{BASE_PATH}/#{deployment_id}", params)
+      end
+
+      # List resources in a deployment
+      # @param deployment_id [String] The deployment ID
+      # @return [Array<Hash>] List of resources
+      def resources(deployment_id)
+        client.get("#{BASE_PATH}/#{deployment_id}/resources")
+      end
+
+      # Get a specific resource from a deployment
+      # @param deployment_id [String] The deployment ID
+      # @param resource_id [String] The resource ID (URL-encoded if contains /)
+      # @return [Hash] Resource details
+      def resource(deployment_id, resource_id)
+        encoded_resource_id = URI.encode_www_form_component(resource_id)
+        client.get("#{BASE_PATH}/#{deployment_id}/resources/#{encoded_resource_id}")
+      end
+
+      # Get the content of a deployment resource
+      # @param deployment_id [String] The deployment ID
+      # @param resource_id [String] The resource ID
+      # @return [String] Raw resource content
+      def resource_data(deployment_id, resource_id)
+        encoded_resource_id = URI.encode_www_form_component(resource_id)
+        client.get("#{BASE_PATH}/#{deployment_id}/resourcedata/#{encoded_resource_id}")
+      end
+
+      alias resource_content resource_data
+    end
+  end
+end

data/lib/flowable/resources/bpmn_history.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+module Flowable
+  module Resources
+    class BpmnHistory < Base
+      # --- Historic Process Instances ---
+
+      # List historic process instances
+      # @param options [Hash] Query parameters
+      # @option options [String] :processInstanceId Filter by process instance ID
+      # @option options [String] :processDefinitionKey Filter by definition key
+      # @option options [String] :processDefinitionId Filter by definition ID
+      # @option options [String] :businessKey Filter by business key
+      # @option options [String] :involvedUser Filter by involved user
+      # @option options [Boolean] :finished Only finished instances
+      # @option options [Boolean] :includeProcessVariables Include variables
+      # @option options [String] :tenantId Filter by tenant
+      # @return [Hash] Paginated list of historic process instances
+      def process_instances(**options)
+        params = paginate_params(options)
+        %i[processInstanceId processDefinitionKey processDefinitionId businessKey
+           involvedUser superProcessInstanceId startedBy tenantId tenantIdLike].each do |key|
+          params[key] = options[key] if options[key]
+        end
+
+        %i[finished includeProcessVariables withoutTenantId].each do |key|
+          params[key] = options[key] if options.key?(key)
+        end
+
+        %i[finishedAfter finishedBefore startedAfter startedBefore].each do |key|
+          params[key] = format_date(options[key]) if options[key]
+        end
+
+        client.get('service/history/historic-process-instances', params)
+      end
+
+      # Get a specific historic process instance
+      # @param process_instance_id [String] The process instance ID
+      # @return [Hash] Historic process instance details
+      def process_instance(process_instance_id)
+        client.get("service/history/historic-process-instances/#{process_instance_id}")
+      end
+
+      # Delete a historic process instance
+      # @param process_instance_id [String] The process instance ID
+      # @return [Boolean] true if successful
+      def delete_process_instance(process_instance_id)
+        client.delete("service/history/historic-process-instances/#{process_instance_id}")
+      end
+
+      # Query historic process instances with complex filters
+      # @param query [Hash] Query body
+      # @return [Hash] Paginated list of historic process instances
+      def query_process_instances(query)
+        client.post('service/query/historic-process-instances', query)
+      end
+
+      # Get identity links for a historic process instance
+      # @param process_instance_id [String] The process instance ID
+      # @return [Array<Hash>] List of identity links
+      def process_instance_identity_links(process_instance_id)
+        client.get("service/history/historic-process-instances/#{process_instance_id}/identitylinks")
+      end
+
+      # --- Historic Activity Instances ---
+
+      # List historic activity instances
+      # @param options [Hash] Query parameters
+      # @option options [String] :activityId Filter by activity ID
+      # @option options [String] :activityName Filter by activity name
+      # @option options [String] :activityType Filter by type (userTask, serviceTask, etc.)
+      # @option options [String] :processInstanceId Filter by process instance
+      # @option options [String] :processDefinitionId Filter by process definition
+      # @option options [Boolean] :finished Only finished activities
+      # @return [Hash] Paginated list of historic activities
+      def activity_instances(**options)
+        params = paginate_params(options)
+        %i[activityId activityName activityType processInstanceId processDefinitionId
+           executionId taskAssignee tenantId tenantIdLike].each do |key|
+          params[key] = options[key] if options[key]
+        end
+
+        params[:finished] = options[:finished] if options.key?(:finished)
+        params[:withoutTenantId] = options[:withoutTenantId] if options.key?(:withoutTenantId)
+
+        client.get('service/history/historic-activity-instances', params)
+      end
+
+      # Query historic activities with complex filters
+      # @param query [Hash] Query body
+      # @return [Hash] Paginated list of historic activities
+      def query_activity_instances(query)
+        client.post('service/query/historic-activity-instances', query)
+      end
+
+      # --- Historic Task Instances ---
+
+      # List historic task instances
+      # @param options [Hash] Query parameters
+      # @option options [String] :taskId Filter by task ID
+      # @option options [String] :processInstanceId Filter by process instance
+      # @option options [String] :processDefinitionId Filter by process definition
+      # @option options [String] :taskName Filter by name
+      # @option options [String] :taskAssignee Filter by assignee
+      # @option options [Boolean] :finished Only finished tasks
+      # @return [Hash] Paginated list of historic tasks
+      def task_instances(**options)
+        params = paginate_params(options)
+        %i[taskId processInstanceId processDefinitionId processDefinitionKey
+           taskName taskNameLike taskDescription taskDescriptionLike
+           taskDefinitionKey taskDeleteReason taskDeleteReasonLike
+           taskAssignee taskAssigneeLike taskOwner taskOwnerLike
+           taskInvolvedUser taskPriority parentTaskId tenantId tenantIdLike].each do |key|
+          params[key] = options[key] if options[key]
+        end
+
+        %i[finished processFinished withoutDueDate includeTaskLocalVariables withoutTenantId].each do |key|
+          params[key] = options[key] if options.key?(key)
+        end
+
+        %i[dueDate dueDateAfter dueDateBefore taskCompletedOn taskCompletedAfter
+           taskCompletedBefore taskCreatedOn taskCreatedBefore taskCreatedAfter].each do |key|
+          params[key] = format_date(options[key]) if options[key]
+        end
+
+        client.get('service/history/historic-task-instances', params)
+      end
+
+      # Get a specific historic task
+      # @param task_id [String] The task ID
+      # @return [Hash] Historic task details
+      def task_instance(task_id)
+        client.get("service/history/historic-task-instances/#{task_id}")
+      end
+
+      # Delete a historic task
+      # @param task_id [String] The task ID
+      # @return [Boolean] true if successful
+      def delete_task_instance(task_id)
+        client.delete("service/history/historic-task-instances/#{task_id}")
+      end
+
+      # Query historic tasks with complex filters
+      # @param query [Hash] Query body
+      # @return [Hash] Paginated list of historic tasks
+      def query_task_instances(query)
+        client.post('service/query/historic-task-instances', query)
+      end
+
+      # --- Historic Variable Instances ---
+
+      # List historic variable instances
+      # @param options [Hash] Query parameters
+      # @option options [String] :processInstanceId Filter by process instance
+      # @option options [String] :taskId Filter by task
+      # @option options [Boolean] :excludeTaskVariables Exclude task variables
+      # @option options [String] :variableName Filter by variable name
+      # @return [Hash] Paginated list of historic variables
+      def variable_instances(**options)
+        params = paginate_params(options)
+        %i[processInstanceId taskId variableName variableNameLike].each do |key|
+          params[key] = options[key] if options[key]
+        end
+
+        params[:excludeTaskVariables] = options[:excludeTaskVariables] if options.key?(:excludeTaskVariables)
+
+        client.get('service/history/historic-variable-instances', params)
+      end
+
+      # Query historic variables with complex filters
+      # @param query [Hash] Query body
+      # @return [Hash] Paginated list of historic variables
+      def query_variable_instances(query)
+        client.post('service/query/historic-variable-instances', query)
+      end
+
+      # --- Historic Detail ---
+
+      # List historic details (variable updates, form properties)
+      # @param options [Hash] Query parameters
+      # @option options [String] :processInstanceId Filter by process instance
+      # @option options [String] :executionId Filter by execution
+      # @option options [String] :activityInstanceId Filter by activity instance
+      # @option options [String] :taskId Filter by task
+      # @option options [Boolean] :selectOnlyFormProperties Only form properties
+      # @option options [Boolean] :selectOnlyVariableUpdates Only variable updates
+      # @return [Hash] Paginated list of historic details
+      def details(**options)
+        params = paginate_params(options)
+        %i[processInstanceId executionId activityInstanceId taskId].each do |key|
+          params[key] = options[key] if options[key]
+        end
+
+        if options.key?(:selectOnlyFormProperties)
+          params[:selectOnlyFormProperties] =
+            options[:selectOnlyFormProperties]
+        end
+        if options.key?(:selectOnlyVariableUpdates)
+          params[:selectOnlyVariableUpdates] =
+            options[:selectOnlyVariableUpdates]
+        end
+
+        client.get('service/history/historic-detail', params)
+      end
+
+      # Query historic details with complex filters
+      # @param query [Hash] Query body
+      # @return [Hash] Paginated list of historic details
+      def query_details(query)
+        client.post('service/query/historic-detail', query)
+      end
+
+      # Aliases for backward compatibility
+      alias tasks task_instances
+      alias activities activity_instances
+      alias variables variable_instances
+
+      private
+
+      def format_date(date)
+        return date if date.is_a?(String)
+        return date.iso8601 if date.respond_to?(:iso8601)
+
+        date.to_s
+      end
+    end
+  end
+end