SmartEngine Documentation

SmartEngine allows you to mount custom logic using the @ExtensionBinding annotation. This mechanism uses a combination of a group and a bindKey to map your implementation to specific engine components. During startup, the AnnotationScanner scans the classpath to build the ExtensionContainer.

Key fields for @ExtensionBinding:

• group: The extension category (defined in ExtensionConstant).
• bindKey: The identifier for the binding (e.g., a BPMN element type, an attribute name, or a behavior name).
• priority: The execution priority for the same bindKey (higher values take precedence).

Common extension groups include:

• element-parser
• attribute-parser
• activity-behavior
• common
• SERVICE

// Example conceptual usage of ExtensionBinding
@ExtensionBinding(group = "activity-behavior", bindKey = "myCustomBehavior", priority = 100)
public class MyCustomBehavior implements ActivityBehavior {
    // implementation
}

To avoid expensive full-partition scans when querying by assigneeId (which does not include the process_instance_id partition key), use a dedicated, non-partitioned index table: se_user_task_index.

How it works

• Purpose: Stores only active/pending tasks to keep the table size small and query performance high.
• Data Redundancy: Redundantly stores common query fields (e.g., process_definition_type, domain_code, title) to avoid JOINs back to the partitioned main tables.
• Lifecycle Management:
  • Insert: When TaskAssignee.insert() is called, insert a record into the index table.
  • Delete: When a task is completed, canceled, or the assignee is deleted, remove the corresponding record from the index table.
  • Update: When task metadata (title, priority, etc.) changes, update the index table.

Schema Implementation

PostgreSQL (with Partial Indexing)

CREATE TABLE se_user_task_index (
  id bigint GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
  tenant_id varchar(64),
  assignee_id varchar(255) NOT NULL,
  assignee_type varchar(128) NOT NULL DEFAULT 'user',
  task_instance_id bigint NOT NULL,
  process_instance_id bigint NOT NULL,
  process_definition_type varchar(255),
  domain_code varchar(64),
  extra jsonb,
  task_status varchar(64) NOT NULL,
  task_gmt_modified timestamp(6),
  title varchar(255),
  priority int DEFAULT 500,
  CONSTRAINT uk_user_task_idx UNIQUE (tenant_id, assignee_id, task_instance_id)
);

-- Optimized partial index for pending tasks
CREATE INDEX idx_user_task_pending ON se_user_task_index
  (tenant_id, assignee_id, assignee_type, task_status)
  WHERE task_status = 'pending';

MySQL

CREATE TABLE se_user_task_index (
  id bigint unsigned NOT NULL AUTO_INCREMENT PRIMARY KEY,
  tenant_id varchar(64),
  assignee_id varchar(255) NOT NULL,
  assignee_type varchar(128) NOT NULL DEFAULT 'user',
  task_instance_id bigint NOT NULL,
  process_instance_id bigint NOT NULL,
  process_definition_type varchar(255),
  domain_code varchar(64),
  extra json,
  task_status varchar(64) NOT NULL,
  task_gmt_modified datetime(6),
  title varchar(255),
  priority int DEFAULT 500,
  UNIQUE KEY uk_user_task_idx (tenant_id, assignee_id, task_instance_id)
);

-- MySQL uses standard composite index as it lacks partial indexes
CREATE INDEX idx_user_task_pending ON se_user_task_index
  (tenant_id, assignee_id, assignee_type, task_status);

-- PostgreSQL Partial Index Example
CREATE INDEX idx_user_task_pending ON se_user_task_index
  (tenant_id, assignee_id, assignee_type, task_status)
  WHERE task_status = 'pending';

SmartEngine provides two mechanisms for extending components for monitoring:

1. Setter Injection: Use this for components that implement specific interfaces and have setter methods in ProcessEngineConfiguration. This is simple, direct, and provides high control.

   • Examples: DelegationExecutor, ListenerExecutor, ExceptionProcessor, VariablePersister, ExpressionEvaluator.

2. @ExtensionBinding: Use this for behavior classes and internal logic that do not have setters. This mechanism uses package scanning to automatically discover and bind implementations.

   • Examples: TransitionBehavior (for gateway decisions), ActivityBehavior implementations, ElementParser implementations, and Service implementations.

Note on Static Utilities: Static tools like ExpressionUtil cannot be injected directly. To monitor them, you must wrap the underlying component they call (e.g., wrap ExpressionEvaluator to monitor ExpressionUtil).

SmartEngine uses a Fluent Query API (chainable query API) inspired by Activiti/Flowable's Query<Q, T> pattern and MyBatis Plus's conditional filtering.

Queries are constructed by calling an entry method on the SmartEngine instance, chaining various filter methods, and concluding with a terminal operation to execute the query.

Query Hierarchy:

• Query<Q, T>: Base interface providing pagination, tenant filtering, and terminal operations.
• ProcessBoundQuery<Q, T>: A shared interface for queries related to a process (e.g., TaskQuery, SupervisionQuery, NotificationQuery). It provides common methods like processInstanceId and sorting.
• ProcessInstanceQuery: A separate branch for querying process instances directly.

// Example of the chainable pattern
List<TaskInstance> tasks = smartEngine.createTaskQuery()
    .taskAssignee("user001")
    .taskStatus(TaskInstanceConstant.PENDING)
    .orderByCreateTime().desc()
    .listPage(0, 10);