flowable 1.0.0

data/lib/flowable/resources/process_instances.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module Flowable
+  module Resources
+    class ProcessInstances < Base
+      BASE_PATH = 'service/runtime/process-instances'
+
+      # List all process instances
+      # @param options [Hash] Query parameters
+      # @option options [String] :id Filter by 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] :suspended Filter suspended instances
+      # @option options [String] :tenantId Filter by tenant
+      # @return [Hash] Paginated list of process instances
+      def list(**options)
+        params = paginate_params(options)
+        %i[id processDefinitionKey processDefinitionId businessKey
+           involvedUser superProcessInstanceId tenantId tenantIdLike].each do |key|
+          params[key] = options[key] if options[key]
+        end
+        params[:suspended] = options[:suspended] if options.key?(:suspended)
+        params[:withoutTenantId] = options[:withoutTenantId] if options.key?(:withoutTenantId)
+        params[:includeProcessVariables] = options[:includeProcessVariables] if options.key?(:includeProcessVariables)
+
+        client.get(BASE_PATH, params)
+      end
+
+      # Get a specific process instance
+      # @param process_instance_id [String] The process instance ID
+      # @return [Hash] Process instance details
+      def get(process_instance_id)
+        client.get("#{BASE_PATH}/#{process_instance_id}")
+      end
+
+      # Start a new process instance by process definition ID
+      # @param process_definition_id [String] The process definition ID
+      # @param variables [Hash] Optional variables (name => value)
+      # @param business_key [String] Optional business key
+      # @param return_variables [Boolean] Return variables in response
+      # @return [Hash] Created process instance
+      def start_by_id(process_definition_id, variables: {}, business_key: nil, return_variables: false)
+        body = { processDefinitionId: process_definition_id }
+        body[:businessKey] = business_key if business_key
+        body[:variables] = build_variables_array(variables) unless variables.empty?
+        body[:returnVariables] = return_variables if return_variables
+
+        client.post(BASE_PATH, body)
+      end
+
+      # Start a new process instance by process definition key
+      # @param process_definition_key [String] The process definition key
+      # @param variables [Hash] Optional variables (name => value)
+      # @param business_key [String] Optional business key
+      # @param tenant_id [String] Optional tenant ID
+      # @param return_variables [Boolean] Return variables in response
+      # @return [Hash] Created process instance
+      def start_by_key(process_definition_key, variables: {}, business_key: nil, tenant_id: nil,
+                       return_variables: false)
+        body = { processDefinitionKey: process_definition_key }
+        body[:businessKey] = business_key if business_key
+        body[:tenantId] = tenant_id if tenant_id
+        body[:variables] = build_variables_array(variables) unless variables.empty?
+        body[:returnVariables] = return_variables if return_variables
+
+        client.post(BASE_PATH, body)
+      end
+
+      # Delete a process instance
+      # @param process_instance_id [String] The process instance ID
+      # @param delete_reason [String] Reason for deletion
+      # @return [Boolean] true if successful
+      def delete(process_instance_id, delete_reason: nil)
+        params = {}
+        params[:deleteReason] = delete_reason if delete_reason
+        client.delete("#{BASE_PATH}/#{process_instance_id}", params)
+      end
+
+      # Suspend a process instance
+      # @param process_instance_id [String] The process instance ID
+      # @return [Hash] Updated process instance
+      def suspend(process_instance_id)
+        client.put("#{BASE_PATH}/#{process_instance_id}", { action: 'suspend' })
+      end
+
+      # Activate a suspended process instance
+      # @param process_instance_id [String] The process instance ID
+      # @return [Hash] Updated process instance
+      def activate(process_instance_id)
+        client.put("#{BASE_PATH}/#{process_instance_id}", { action: 'activate' })
+      end
+
+      # Query process instances with complex filters
+      # @param query [Hash] Query body with filters and variable conditions
+      # @return [Hash] Paginated list of process instances
+      def query(query)
+        client.post('service/query/process-instances', query)
+      end
+
+      # Get the diagram/image for a process instance
+      # @param process_instance_id [String] The process instance ID
+      # @return [String] Binary image data
+      def diagram(process_instance_id)
+        client.get("#{BASE_PATH}/#{process_instance_id}/diagram")
+      end
+
+      # --- Identity Links ---
+
+      # Get involved people for a process instance
+      # @param process_instance_id [String] The process instance ID
+      # @return [Array<Hash>] List of identity links
+      def identity_links(process_instance_id)
+        client.get("#{BASE_PATH}/#{process_instance_id}/identitylinks")
+      end
+
+      # Add an involved user to a process instance
+      # @param process_instance_id [String] The process instance ID
+      # @param user_id [String] The user ID
+      # @param type [String] Type of involvement (e.g., 'participant')
+      # @return [Hash] Created identity link
+      def add_involved_user(process_instance_id, user_id, type: 'participant')
+        client.post(
+          "#{BASE_PATH}/#{process_instance_id}/identitylinks",
+          { userId: user_id, type: type }
+        )
+      end
+
+      # Remove an involved user from a process instance
+      # @param process_instance_id [String] The process instance ID
+      # @param user_id [String] The user ID
+      # @param type [String] Type of involvement
+      # @return [Boolean] true if successful
+      def remove_involved_user(process_instance_id, user_id, type)
+        client.delete("#{BASE_PATH}/#{process_instance_id}/identitylinks/users/#{user_id}/#{type}")
+      end
+
+      # --- Variables ---
+
+      # Get all variables for a process instance
+      # @param process_instance_id [String] The process instance ID
+      # @return [Array<Hash>] List of variables
+      def variables(process_instance_id)
+        client.get("#{BASE_PATH}/#{process_instance_id}/variables")
+      end
+
+      # Get a specific variable from a process instance
+      # @param process_instance_id [String] The process instance ID
+      # @param variable_name [String] The variable name
+      # @return [Hash] Variable details
+      def variable(process_instance_id, variable_name)
+        client.get("#{BASE_PATH}/#{process_instance_id}/variables/#{variable_name}")
+      end
+
+      # Create variables on a process instance (fails if exists)
+      # @param process_instance_id [String] The process instance ID
+      # @param variables [Hash] Variables to create (name => value)
+      # @return [Array<Hash>] Created variables
+      def create_variables(process_instance_id, variables)
+        client.post(
+          "#{BASE_PATH}/#{process_instance_id}/variables",
+          build_variables_array(variables)
+        )
+      end
+
+      # Create or update variables on a process instance
+      # @param process_instance_id [String] The process instance ID
+      # @param variables [Hash] Variables to set (name => value)
+      # @return [Array<Hash>] Updated variables
+      def set_variables(process_instance_id, variables)
+        client.put(
+          "#{BASE_PATH}/#{process_instance_id}/variables",
+          build_variables_array(variables)
+        )
+      end
+
+      # Update a single variable on a process instance
+      # @param process_instance_id [String] The process instance ID
+      # @param name [String] Variable name
+      # @param value [Object] Variable value
+      # @param type [String] Optional explicit type
+      # @return [Hash] Updated variable
+      def update_variable(process_instance_id, name, value, type: nil)
+        body = { name: name, value: value }
+        body[:type] = type || infer_type(value)
+
+        client.put("#{BASE_PATH}/#{process_instance_id}/variables/#{name}", body)
+      end
+
+      # Delete a variable from a process instance
+      # @param process_instance_id [String] The process instance ID
+      # @param variable_name [String] The variable name
+      # @return [Boolean] true if successful
+      def delete_variable(process_instance_id, variable_name)
+        client.delete("#{BASE_PATH}/#{process_instance_id}/variables/#{variable_name}")
+      end
+    end
+  end
+end

data/lib/flowable/resources/tasks.rb

@@ -0,0 +1,281 @@
+# frozen_string_literal: true
+
+module Flowable
+  module Resources
+    class Tasks < Base
+      BASE_PATH = 'cmmn-runtime/tasks'
+
+      # List all tasks
+      # @param options [Hash] Query parameters
+      # @option options [String] :name Filter by exact name
+      # @option options [String] :nameLike Filter by name pattern
+      # @option options [String] :assignee Filter by assignee
+      # @option options [String] :owner Filter by owner
+      # @option options [String] :candidateUser Tasks claimable by user
+      # @option options [String] :candidateGroup Tasks claimable by group
+      # @option options [String] :caseInstanceId Filter by case instance
+      # @option options [String] :caseDefinitionId Filter by case definition
+      # @option options [Boolean] :unassigned Only unassigned tasks
+      # @option options [Boolean] :active Only active tasks
+      # @option options [String] :tenantId Filter by tenant
+      # @return [Hash] Paginated list of tasks
+      def list(**options)
+        params = paginate_params(options)
+        %i[name nameLike description assignee assigneeLike owner ownerLike
+           candidateUser candidateGroup candidateGroups involvedUser
+           taskDefinitionKey taskDefinitionKeyLike caseInstanceId
+           caseDefinitionId tenantId tenantIdLike category].each do |key|
+          params[key] = options[key] if options[key]
+        end
+
+        # Integer/Date filters
+        params[:priority] = options[:priority] if options[:priority]
+        params[:minimumPriority] = options[:minimumPriority] if options[:minimumPriority]
+        params[:maximumPriority] = options[:maximumPriority] if options[:maximumPriority]
+
+        # Boolean filters
+        %i[unassigned active excludeSubTasks withoutDueDate
+           includeTaskLocalVariables withoutTenantId].each do |key|
+          params[key] = options[key] if options.key?(key)
+        end
+
+        # Date filters
+        %i[createdOn createdBefore createdAfter dueOn dueBefore dueAfter].each do |key|
+          params[key] = format_date(options[key]) if options[key]
+        end
+
+        client.get(BASE_PATH, params)
+      end
+
+      # Get a specific task
+      # @param task_id [String] The task ID
+      # @return [Hash] Task details
+      def get(task_id)
+        client.get("#{BASE_PATH}/#{task_id}")
+      end
+
+      # Update a task
+      # @param task_id [String] The task ID
+      # @param attributes [Hash] Attributes to update
+      # @option attributes [String] :name Task name
+      # @option attributes [String] :description Task description
+      # @option attributes [String] :assignee Assignee user ID
+      # @option attributes [String] :owner Owner user ID
+      # @option attributes [Integer] :priority Priority (default: 50)
+      # @option attributes [String] :dueDate Due date (ISO-8601)
+      # @option attributes [String] :category Task category
+      # @return [Hash] Updated task
+      def update(task_id, **attributes)
+        body = {}
+        %i[name description assignee owner parentTaskId category
+           formKey delegationState tenantId].each do |key|
+          body[key] = attributes[key] if attributes.key?(key)
+        end
+        body[:priority] = attributes[:priority] if attributes[:priority]
+        body[:dueDate] = format_date(attributes[:dueDate]) if attributes[:dueDate]
+
+        client.put("#{BASE_PATH}/#{task_id}", body)
+      end
+
+      # Delete a task
+      # @param task_id [String] The task ID
+      # @param cascade_history [Boolean] Also delete historic task
+      # @param delete_reason [String] Reason for deletion
+      # @return [Boolean] true if successful
+      def delete(task_id, cascade_history: false, delete_reason: nil)
+        params = {}
+        params[:cascadeHistory] = cascade_history if cascade_history
+        params[:deleteReason] = delete_reason if delete_reason
+
+        client.delete("#{BASE_PATH}/#{task_id}", params)
+      end
+
+      # --- Task Actions ---
+
+      # Complete a task
+      # @param task_id [String] The task ID
+      # @param variables [Hash] Optional variables to set (name => value)
+      # @param outcome [String] Optional outcome
+      # @return [Hash] Response
+      def complete(task_id, variables: {}, outcome: nil)
+        body = { action: 'complete' }
+        body[:variables] = build_variables_array(variables) unless variables.empty?
+        body[:outcome] = outcome if outcome
+
+        client.post("#{BASE_PATH}/#{task_id}", body)
+      end
+
+      # Claim a task
+      # @param task_id [String] The task ID
+      # @param assignee [String] User to assign the task to
+      # @return [Hash] Response
+      def claim(task_id, assignee)
+        client.post("#{BASE_PATH}/#{task_id}", { action: 'claim', assignee: assignee })
+      end
+
+      # Unclaim a task (set assignee to null)
+      # @param task_id [String] The task ID
+      # @return [Hash] Response
+      def unclaim(task_id)
+        client.post("#{BASE_PATH}/#{task_id}", { action: 'claim', assignee: nil })
+      end
+
+      # Delegate a task to another user
+      # @param task_id [String] The task ID
+      # @param assignee [String] User to delegate to
+      # @return [Hash] Response
+      def delegate(task_id, assignee)
+        client.post("#{BASE_PATH}/#{task_id}", { action: 'delegate', assignee: assignee })
+      end
+
+      # Resolve a delegated task
+      # @param task_id [String] The task ID
+      # @return [Hash] Response
+      def resolve(task_id)
+        client.post("#{BASE_PATH}/#{task_id}", { action: 'resolve' })
+      end
+
+      # --- Variables ---
+
+      # Get all variables for a task
+      # @param task_id [String] The task ID
+      # @param scope [String] 'local', 'global', or nil for both
+      # @return [Array<Hash>] List of variables
+      def variables(task_id, scope: nil)
+        params = {}
+        params[:scope] = scope if scope
+        client.get("#{BASE_PATH}/#{task_id}/variables", params)
+      end
+
+      # Get a specific variable from a task
+      # @param task_id [String] The task ID
+      # @param variable_name [String] The variable name
+      # @param scope [String] 'local' or 'global'
+      # @return [Hash] Variable details
+      def variable(task_id, variable_name, scope: nil)
+        params = {}
+        params[:scope] = scope if scope
+        client.get("#{BASE_PATH}/#{task_id}/variables/#{variable_name}", params)
+      end
+
+      # Create variables on a task
+      # @param task_id [String] The task ID
+      # @param variables [Hash] Variables to create (name => value)
+      # @param scope [String] 'local' or 'global' (default: local)
+      # @return [Array<Hash>] Created variables
+      def create_variables(task_id, variables, scope: 'local')
+        vars = build_variables_array(variables).map { |v| v.merge(scope: scope) }
+        client.post("#{BASE_PATH}/#{task_id}/variables", vars)
+      end
+
+      # Set (update or create) variables on a task
+      # Updates each variable individually using PUT to /variables/{name}
+      # Creates variables that don't exist using POST
+      # @param task_id [String] The task ID
+      # @param variables [Hash] Variables to set (name => value)
+      # @param scope [String] 'local' or 'global' (default: local)
+      # @return [Array<Hash>] Updated/created variables
+      def set_variables(task_id, variables, scope: 'local')
+        results = []
+        variables.each do |name, value|
+          # Try to update existing variable
+          result = update_variable(task_id, name.to_s, value, scope: scope)
+          results << result
+        rescue Flowable::NotFoundError
+          # Variable doesn't exist, create it
+          vars = [{ name: name.to_s, value: value, scope: scope, type: infer_type(value) }]
+          created = client.post("#{BASE_PATH}/#{task_id}/variables", vars)
+          results.concat(created.is_a?(Array) ? created : [created])
+        end
+        results
+      end
+
+      # Update a variable on a task
+      # @param task_id [String] The task ID
+      # @param name [String] Variable name
+      # @param value [Object] Variable value
+      # @param scope [String] 'local' or 'global'
+      # @return [Hash] Updated variable
+      def update_variable(task_id, name, value, scope: 'local')
+        body = { name: name, value: value, scope: scope, type: infer_type(value) }
+        client.put("#{BASE_PATH}/#{task_id}/variables/#{name}", body)
+      end
+
+      # Delete a variable from a task
+      # @param task_id [String] The task ID
+      # @param variable_name [String] The variable name
+      # @param scope [String] 'local' or 'global'
+      # @return [Boolean] true if successful
+      def delete_variable(task_id, variable_name, scope: 'local')
+        client.delete("#{BASE_PATH}/#{task_id}/variables/#{variable_name}", { scope: scope })
+      end
+
+      # Delete all local variables from a task
+      # @param task_id [String] The task ID
+      # @return [Boolean] true if successful
+      def delete_all_local_variables(task_id)
+        client.delete("#{BASE_PATH}/#{task_id}/variables")
+      end
+
+      # --- Identity Links ---
+
+      # Get all identity links for a task
+      # @param task_id [String] The task ID
+      # @return [Array<Hash>] List of identity links
+      def identity_links(task_id)
+        client.get("#{BASE_PATH}/#{task_id}/identitylinks")
+      end
+
+      # Get identity links for users only
+      # @param task_id [String] The task ID
+      # @return [Array<Hash>] List of user identity links
+      def user_identity_links(task_id)
+        client.get("#{BASE_PATH}/#{task_id}/identitylinks/users")
+      end
+
+      # Get identity links for groups only
+      # @param task_id [String] The task ID
+      # @return [Array<Hash>] List of group identity links
+      def group_identity_links(task_id)
+        client.get("#{BASE_PATH}/#{task_id}/identitylinks/groups")
+      end
+
+      # Create an identity link (user) on a task
+      # @param task_id [String] The task ID
+      # @param user_id [String] The user ID
+      # @param type [String] Link type (e.g., 'candidate')
+      # @return [Hash] Created identity link
+      def add_user_identity_link(task_id, user_id, type: 'candidate')
+        client.post("#{BASE_PATH}/#{task_id}/identitylinks", { userId: user_id, type: type })
+      end
+
+      # Create an identity link (group) on a task
+      # @param task_id [String] The task ID
+      # @param group_id [String] The group ID
+      # @param type [String] Link type (e.g., 'candidate')
+      # @return [Hash] Created identity link
+      def add_group_identity_link(task_id, group_id, type: 'candidate')
+        client.post("#{BASE_PATH}/#{task_id}/identitylinks", { groupId: group_id, type: type })
+      end
+
+      # Delete an identity link from a task
+      # @param task_id [String] The task ID
+      # @param family [String] 'users' or 'groups'
+      # @param identity_id [String] The user or group ID
+      # @param type [String] Link type
+      # @return [Boolean] true if successful
+      def delete_identity_link(task_id, family, identity_id, type)
+        client.delete("#{BASE_PATH}/#{task_id}/identitylinks/#{family}/#{identity_id}/#{type}")
+      end
+
+      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

data/lib/flowable/version.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Flowable
+  # Gem version
+  VERSION = '1.0.0'
+
+  # Minimum supported Flowable REST API version
+  FLOWABLE_API_VERSION = '7.1.0'
+
+  # Version information hash
+  VERSION_INFO = {
+    major: 1,
+    minor: 0,
+    patch: 0,
+    pre: nil
+  }.freeze
+
+  class << self
+    # Returns the gem version string
+    # @return [String] version string (e.g., "1.0.0")
+    def version
+      VERSION
+    end
+
+    # Returns full version information
+    # @return [Hash] version info hash
+    def version_info
+      VERSION_INFO
+    end
+
+    # Returns the supported Flowable API version
+    # @return [String] Flowable API version
+    def flowable_api_version
+      FLOWABLE_API_VERSION
+    end
+  end
+end