当前位置：首页 > news >正文

9、Activiti-任务（Task）的相关操作

news 2025/5/14 8:13:13

1. 引言

Activiti是一个轻量级、开源的工作流和业务流程管理(BPM)平台，基于Java开发。它实现了BPMN 2.0规范，提供了强大的流程定义、执行和监控能力。在Activiti中，任务(Task)是流程执行的核心概念之一，代表需要人工参与完成的工作项。

任务操作API是Activiti提供的RESTful和Java API集合，用于对流程中的任务进行各种操作。Activiti的任务操作功能非常丰富，涵盖了任务生命周期管理、变量处理、身份链接、评论与附件等多个方面。

2. 任务操作概述

2.1. 任务操作功能体系

Activiti的任务操作功能可以划分为以下几个主要类别：

基础任务操作：包括获取、查询、更新和删除任务等基本CRUD操作
任务变量管理：处理与任务相关的各种变量，包括创建、更新、删除等
身份链接管理：处理任务与用户/组之间的关联关系
评论与附件：为任务添加评论和附件，丰富任务内容
历史任务查询：查询已完成任务的历史记录

2.2. 任务模型

在Activiti中，任务(Task)是org.activiti.api.task.model.Task接口的实例，主要包含以下属性：

方法名称	说明
enum TaskStatus { CREATED, ASSIGNED, SUSPENDED, COMPLETED, CANCELLED, DELETED }	定义任务的当前生命周期状态： CREATED：任务已创建但未分配（未认领）。 ASSIGNED：任务已分配给某人（已认领）。 SUSPENDED：任务被挂起（暂时不可操作）。 COMPLETED：任务已完成。 CANCELLED：任务被取消。 DELETED：任务被删除。
String getId()	任务的唯一标识符（UUID 或数据库主键）
String getOwner()	任务的原属用户（任务创建者或初始责任人）
String getAssignee()	任务的当前处理人（认领任务的人）
String getName()	任务名称（如“审批申请”、“处理投诉”）
String getDescription()	任务的详细描述
Date getCreatedDate()	任务的创建时间
Date getClaimedDate()	任务被认领的时间（从 `CREATED` 变为 `ASSIGNED` 的时间点
Date getDueDate()	任务的截止时间（超时未完成可能触发警告或自动操作）
int getPriority()	任务优先级（数值越高优先级越高，如 0=低，100=高）
String getProcessDefinitionId()	关联的流程定义ID（标识任务所属的流程定义）
String getProcessInstanceId()	关联的流程实例ID（标识任务所属的具体流程实例）
String getParentTaskId()	父任务ID（用于子任务场景，如会签任务中的子任务）
TaskStatus getStatus()	任务的当前状态（参考 `TaskStatus` 枚举）
String getFormKey()	关联的表单KEY（用于动态渲染任务处理表单）
Date getCompletedDate()	任务完成时间（状态为 `COMPLETED` 时有效）
Long getDuration()	任务从创建到完成的耗时（毫秒，仅完成的任务有值）
Integer getProcessDefinitionVersion()	流程定义的版本号（用于区分同一流程定义的不同版本）
String getBusinessKey()	业务主键（通常关联业务系统的ID，如订单号、合同号等）
boolean isStandalone()	是否为独立任务（`true` 表示非流程关联的任务，如手动创建的任务）

3. 基础任务操作

3.1. 根据taskId获取单个任务

3.1.1. 特点

通过任务ID精确获取特定任务对象，是其他任务操作的基础。

3.1.2. 使用场景

当已知任务ID需要获取任务详细信息时使用

3.1.3. 查询示例

3.1.3.1. 方式一：TaskService taskService


public AjaxResult getATask(String taskId) {Task task = taskService.createTaskQuery().taskId(taskId).singleResult();return AjaxResult.success(new TaskDomain(task).toString());
}

3.1.3.2. 方式二：TaskRuntime taskRuntime

    public AjaxResult getATask(String taskId) {Task task = taskRuntime.task(taskId);return AjaxResult.success(new TaskDTO(task).toString());}

3.2. 查询任务列表

3.2.1. 特点

支持多种条件组合查询，可分页返回结果。

3.2.2. 使用场景

需要列出满足特定条件的任务集合，如待办任务列表。

3.2.3. 查询示例

3.2.3.1. 方式一：TaskService taskService

    public AjaxResult listOfTasks() {List<Task> tasks = taskService.createTaskQuery().list();//  如果需要分页处理 将 list()替换为 .listPage(0,10)return AjaxResult.success(tasks.stream().map(t -> new TaskDomain(t)).collect(Collectors.toList()));}

3.2.3.2. 方式二：TaskRuntime taskRuntime

    @Resourceprivate APITaskConverter taskConverter;public AjaxResult listOfTasks() {// 1、获取任务查询对象TaskQuery taskQuery = taskService.createTaskQuery();//2、将org.activiti.engine.task.Task 接口转换为 org.activiti.api.task.model.TaskList<Task> tasks = taskConverter.from(taskQuery.list());// 3、获取任务数据查询条目数量Page<Task> taskPage = new PageImpl<>(tasks, Math.toIntExact(taskQuery.count()));int totalItems = taskPage.getTotalItems();return AjaxResult.success("数据详情：" + tasks.stream().map(t -> new TaskDTO(t)).collect(Collectors.toList()) + "; 数量：" + totalItems);}

3.2.3.3. 查询条件

分类	方法	说明
按照任务名称查询	`taskName(String name)`	按任务名称精确匹配
	`taskNameIn(List<String>)`	按任务名称列表查询（区分大小写）
	`taskNameInIgnoreCase(List<String>)`	按任务名称列表查询（不区分大小写）
	`taskNameLike(String)`	按任务名称模糊匹配（SQL语法，如 `%activiti%`）
	`taskNameLikeIgnoreCase(String)`	按任务名称模糊匹配（不区分大小写）
按照任务描述查询	`taskDescription(String)`	按任务描述精确匹配
	`taskDescriptionLike(String)`	按任务描述模糊匹配
	`taskDescriptionLikeIgnoreCase(String)`	按任务描述模糊匹配（不区分大小写）
按照优先级查询	`taskPriority(Integer)`	按优先级精确匹配
	`taskMinPriority(Integer)`	查询优先级≥指定值的任务
	`taskMaxPriority(Integer)`	查询优先级≤指定值的任务
按照处理人查询	`taskAssignee(String)`	按当前处理人（Assignee）精确匹配
	`taskAssigneeLike(String)`	按处理人模糊匹配（如 `%admin%`）
	`taskAssigneeLikeIgnoreCase(String)`	按处理人模糊匹配（不区分大小写）
	`taskAssigneeIds(List<String>)`	按处理人ID列表查询
按照任务所有者查询	`taskOwner(String)`	按任务所有者（Owner）精确匹配
	`taskOwnerLike(String)`	按所有者模糊匹配
	`taskOwnerLikeIgnoreCase(String)`	按所有者模糊匹配（不区分大小写）
按照任务候选人/组查询	`taskCandidateUser(String)`	查询用户为候选人的任务（含用户所在组的任务）
	`taskCandidateUser(String, List<String>)`	查询用户为候选人的任务（指定用户组）
	`taskCandidateGroup(String)`	查询组为候选人的任务
	`taskCandidateGroupIn(List<String>)`	按候选组列表查询
按照任务参与人/组查询	`taskInvolvedUser(String)`	查询用户参与的任务（含处理人、所有者、候选人）
按照任务参与人/组查询	`taskInvolvedGroupsIn(List<String>)`	查询指定组参与的任务
按照租户查询	`taskTenantId(String tenantId)`	查询具有给定租户id的任务
	`taskTenantIdLike(String tenantIdLike)`	租户id模糊匹配
	`taskWithoutTenantId()`	查询没有租户id的任务
按流程实例关联查询	`processInstanceId(String)`	按流程实例ID查询
	`processInstanceIdIn(List<String>)`	按流程实例ID列表查询
	`processInstanceBusinessKey(String)`	按业务键（BusinessKey）精确匹配
	`processInstanceBusinessKeyLike(String)`	按业务键模糊匹配
	`processInstanceBusinessKeyLikeIgnoreCase(String)`	按业务键模糊匹配（不区分大小写）
	`executionId(String)`	按执行ID查询
按时间范围查询	`taskCreatedOn(Date)`	查询指定创建时间的任务
	`taskCreatedBefore(Date)`	查询创建时间≤指定日期的任务
	`taskCreatedAfter(Date)`	查询创建时间≥指定日期的任务
	`taskDueDate(Date)`	查询指定截止时间的任务
	`taskDueBefore(Date)`	查询截止时间≤指定日期的任务
	`taskDueAfter(Date)`	查询截止时间≥指定日期的任务
	`withoutTaskDueDate()`	查询无截止时间的任务
按照任务类别查询	`taskCategory(String category)`	查询给定类别的任务
按流程定义关联查询	`processDefinitionKey(String)`	按流程定义Key精确匹配
	`processDefinitionKeyLike(String)`	按流程定义Key模糊匹配
	`processDefinitionKeyLikeIgnoreCase(String)`	按流程定义Key模糊匹配（不区分大小写）
	`processDefinitionKeyIn(List<String>)`	按流程定义Key列表查询
	`processDefinitionId(String)`	按流程定义ID查询
	`processDefinitionName(String)`	按流程定义名称精确匹配
	`processDefinitionNameLike(String)`	按流程定义名称模糊匹配
	`processCategoryIn(List<String>)`	查询流程分类在指定列表中的任务
	`processCategoryNotIn(List<String>)`	查询流程分类不在指定列表中的任务
	`deploymentId(String)`	按部署ID查询
	`deploymentIdIn(List<String>)`	按部署ID列表查询
按照变量查询	`taskVariableValueEquals(String, Object)`	按本地任务变量名和值精确匹配
	`taskVariableValueEquals(Object)`	查询存在指定值的本地任务变量
	`taskVariableValueEqualsIgnoreCase(String, String)`	按字符串变量值匹配（不区分大小写）
	`taskVariableValueNotEquals(String, Object)`	按本地变量名和值不匹配查询
	`taskVariableValueNotEqualsIgnoreCase(String, String)`	按字符串变量值不匹配（不区分大小写）
	`taskVariableValueGreaterThan(String, Object)`	查询变量值>指定值的任务
	`taskVariableValueGreaterThanOrEqual(String, Object)`	查询变量值≥指定值的任务
	`taskVariableValueLessThan(String, Object)`	查询变量值<指定值的任务
	`taskVariableValueLessThanOrEqual(String, Object)`	查询变量值≤指定值的任务
	`taskVariableValueLike(String, String)`	按字符串变量模糊匹配（如 `%activiti%`）
	`taskVariableValueLikeIgnoreCase(String, String)`	按字符串变量模糊匹配（不区分大小写）
	`processVariableValueEquals(String, Object)`	按流程变量名和值精确匹配
	`processVariableValueEquals(Object)`	查询存在指定值的流程变量
	`processVariableValueEqualsIgnoreCase(String, String)`	按流程字符串变量匹配（不区分大小写）
	`processVariableValueNotEquals(String, Object)`	按流程变量名和值不匹配查询
	`processVariableValueNotEqualsIgnoreCase(String, String)`	按流程字符串变量不匹配（不区分大小写）
	`processVariableValueGreaterThan(String, Object)`	查询流程变量值>指定值的任务
	`processVariableValueLessThan(String, Object)`	查询流程变量值<指定值的任务
按结果控制与本地化查询	`includeTaskLocalVariables()`	在结果中包含本地任务变量
	`includeProcessVariables()`	在结果中包含流程变量
	`limitTaskVariables(Integer)`	限制返回的变量数量
	`locale(String)`	指定任务名称和描述的本地化语言
	`withLocalizationFallback()`	启用本地化回退（找不到指定语言时使用默认语言）
逻辑组合查询	`or()`	开始一个OR条件组合，后续条件用OR连接
逻辑组合查询	`endOr()`	结束OR条件组合，回归默认的AND连接
排序	`orderByTaskId()`	按任务ID排序（需搭配 `asc()`/`desc()`）
	`orderByTaskName()`	按任务名称排序
	`orderByTaskDescription()`	按任务描述排序
	`orderByTaskPriority()`	按优先级排序
	`orderByTaskAssignee()`	按处理人排序
	`orderByTaskCreateTime()`	按创建时间排序
	`orderByProcessInstanceId()`	按流程实例ID排序
	`orderByExecutionId()`	按执行ID排序
	`orderByProcessDefinitionId()`	按流程定义ID排序
	`orderByTaskDueDate()`	按截止时间排序
	`orderByTaskOwner()`	按所有者排序
	`orderByTaskDefinitionKey()`	按任务定义Key排序
	`orderByTenantId()`	按租户ID排序
	`orderByDueDateNullsFirst()`	截止时间NULL值排在最前
	`orderByDueDateNullsLast()`	截止时间NULL值排在最后

3.3. 更新任务

3.3.1. 特点

可更新任务的各种属性，如名称、描述、优先级等。

3.3.2. 使用场景

需要修改任务属性时使用。

3.3.3. 更新示例

3.3.3.1. 修改任务所有者

taskService.setOwner(taskId,"admin");

3.3.3.2. 修改任务处理人

taskService.setAssignee(taskId,"zhaoyun");

3.3.3.3. 修改任务优先级

taskService.setPriority(taskId,72);

3.3.3.4. 修改任务到期时间

taskService.setDueDate(taskId,new Date() );

3.3.3.5. 通过taskRuntime更新任务

taskRuntime.update(new UpdateTaskPayload(taskId,"审批","system/user",new Date() ,80,"admin","",""));

字段名	类型	说明
`taskId`	`String`	要更新的任务ID（必填）
`name`	`String`	新任务名称（可选）
`description`	`String`	新任务描述（可选）
`dueDate`	`Date`	新截止时间（可选）
`priority`	`Integer`	新优先级（可选）
`assignee`	`String`	新处理人（可选）
`parentTaskId`	`String`	新父任务ID（可选）

3.4. 任务操作

3.4.1. 特点

包括认领、完成、委派等核心操作。

3.4.2. 使用场景

处理任务流转的关键操作。

3.4.3. 示例

3.4.3.1. 领取任务

3.4.3.1.1. 使用TaskService

taskService.claim(taskId,"admin")

3.4.3.1.2. 使用TaskRuntime

taskRuntime.claim(new ClaimTaskPayload(taskId,""))

3.4.3.2. 释放任务

3.4.3.2.1. 使用TaskService

taskService.unclaim(taskId);

3.4.3.2.2. 使用TaskRuntime

taskRuntime.release(new ReleaseTaskPayload(taskId));

3.4.3.3. 委派任务

taskService.delegateTask(taskId,"admin");

3.4.3.4. 解决任务

taskService.resolveTask(taskId);

3.4.3.4.1. resolveTask重载方法说明

方法签名	参数说明	关键特性	适用场景
`void resolveTask(String taskId)`	`taskId` : 要解决的任务ID（必填）	将委托任务标记为已解决（`RESOLVED` ），不传递任何变量。	任务处理人完成委托后，无需向流程传递额外数据时使用。
`void resolveTask(String taskId,<br> Map<String, Object> variables)`	`variables` : 持久化变量（存入数据库，可选）	解决任务时提交持久化变量，供后续流程节点使用。	需要记录审批结果、表单数据等需长期保存的信息时使用。
`void resolveTask(String taskId,<br> Map<String, Object> variables,<br> Map<String, Object> transientVariables)`	`transientVariables` : 临时变量（仅当前操作有效，不存储到数据库，可选）	解决任务时同时提交持久化和临时变量。	需传递临时数据（如通知消息）且避免污染流程变量表时使用。

3.4.3.5. 完成任务

3.4.3.5.1. 使用TaskService

taskService.complete(taskId);

3.4.3.5.2. complete重载方法说明

方法签名	参数说明	关键特性	适用场景
`void complete(String taskId)`	`taskId` : 要完成的任务ID	仅完成任务，不传递任何变量	任务无需携带额外数据时使用
`void complete(String taskId,<br> Map<String, Object> variables)`	`variables` : 流程级变量（全局可见，存入数据库）	提交持久化变量，后续流程节点可读取	需要传递审批结果等持久化数据时
`void complete(String taskId,<br> Map<String, Object> variables,<br> Map<String, Object> transientVariables)`	`transientVariables` : 临时变量（仅当前生命周期有效，不存储）	同时传递持久化和临时变量	需临时传递消息（如通知内容）且避免污染流程变量
`void complete(String taskId,<br> Map<String, Object> variables,<br> boolean localScope)`	`localScope` : 变量作用域（true=任务级，false=流程级，默认false）	控制变量作用范围，任务级变量仅当前任务可见	需要限制变量作用域（如临时表单数据）

3.4.3.5.3. 使用TaskRuntime

taskRuntime.complete(new CompleteTaskPayload());

3.5. 删除任务

3.5.1. 特点

删除任务及其相关数据，需谨慎使用。

3.5.2. 使用场景

需要取消或删除无效任务时使用。

3.5.3. 示例

3.5.3.1. 使用TaskService

taskService.deleteTask(taskId);
taskService.deleteTasks(Collections.singleton(taskId));

3.5.3.1.1. deleteTask及deleteTasks重载方法说明

法签名	参数说明	功能特点	适用场景
`void deleteTask(String taskId)`	`taskId` : 要删除的任务ID	删除任务但保留历史记录	常规任务删除，需审计留痕时使用
`void deleteTask(String taskId, boolean cascade)`	`cascade` : 是否级联删除历史记录（true=删除）	控制是否同步清理历史数据	需要彻底清理任务所有痕迹时使用
`void deleteTask(String taskId, String deleteReason)`	`deleteReason` : 删除原因（记录到历史）	删除任务并记录原因（历史模块启用时可见）	需要追踪删除操作的业务场景（如"用户撤销"）
`void deleteTask(String taskId, String deleteReason, boolean cancel)`	`cancel` : 是否标记为"已取消"（影响业务状态）	删除任务时附加状态标记和原因	需要区分正常完成与取消的场景（如工单作废）
`void deleteTasks(Collection<String> taskIds)`	`taskIds`: 要删除的任务ID集合	批量删除任务但保留历史记录	清理多个任务同时需保留审计轨迹
`void deleteTasks(Collection<String> taskIds, boolean cascade)`	`cascade`: 是否级联删除历史记录（true=同步清理）	批量删除任务并可选清理历史数据	需要彻底移除任务及其历史痕迹（如数据迁移后）
`void deleteTasks(Collection<String> taskIds, String deleteReason)`	`deleteReason`: 统一删除原因（记录到历史）	批量删除任务并记录统一原因	需要记录批量操作原因（如"系统批量清理"）
`void deleteTasks(Collection<String> taskIds, String deleteReason, boolean cancel)`	`cancel`: 是否标记为"已取消"	批量删除任务时附加状态标记和原因	需要批量作废任务（如订单批量取消）

3.5.3.2. 使用TaskRuntime

taskRuntime.delete(new DeleteTaskPayload(taskId,"无用信息"));

4. 任务变量操作

4.1. 获取任务的所有（多个）变量

4.1.1. 特点

返回任务的所有变量Map，变量值已反序列化。

4.1.2. 示例

4.1.2.1. 使用TaskService

taskService.getVariables(taskId);
// 或
taskService.getVariablesLocal(taskId);

4.1.2.1.1. getVariables重载方法说明

方法签名	参数说明	作用域	典型使用场景
`Map<String, Object> getVariables(String taskId)`	`taskId`：任务ID	任务作用域 + 执行作用域	需要获取任务所有关联变量时
`Map<String, Object> getVariables(String taskId, Collection<String> variableNames)`	`taskId`：任务ID `variableNames`：指定变量名集合	仅任务作用域	只需要获取特定变量时

4.1.2.1.2. getVariablesLocal重载方法说明

方法签名

参数说明

作用域

典型使用场景

Map<String, Object> getVariablesLocal(String taskId)

taskId

：任务ID

仅搜索当前任务作用域（Task Local Scope）

1. 需要获取任务所有本地变量
2. 需要完整变量快照

Map<String, Object> getVariablesLocal(String taskId, Collection<String> variableNames)

taskId

：任务ID
variableNames

：指定变量名集合

仅搜索当前任务作用域（Task Local Scope）

1. 只需要获取特定变量集合
2. 需要优化查询性能

4.1.2.2. 使用TaskRuntime

//返回一个List<VariableInstance>，包含匹配查询条件的所有变量实例
taskRuntime.variables(new GetTaskVariablesPayload(taskId));

4.2. 从任务中获取指定变量

4.2.1. 特点

按变量名获取特定变量，支持指定是否从父作用域获取。

4.2.2. 示例

taskService.getVariable(taskId,"name");
// 或
taskService.getVariableLocal(taskId,"name");

4.2.2.1. getVariable重载方法：

方法签名	参数说明	作用域	典型使用场景
`Object getVariable(String taskId, String variableName)`	`taskId`：要查询的任务ID `variableName`：变量名称	先搜索任务作用域（Task Scope）若未找到，再搜索执行作用域（Execution Scope）	获取变量但不确定其类型需要动态处理变量值（如JSON解析）兼容旧代码或弱类型场景
`<T> T getVariable(String taskId, String variableName, Class<T> variableClass)`	`taskId`：要查询的任务ID `variableName`：变量名称 `variableClass`：目标类型（如 String.class、Integer.class）	先搜索任务作用域（Task Scope）若未找到，再搜索执行作用域（Execution Scope）	需要类型安全的变量访问直接获取特定类型的变量（如 Integer、Boolean）减少手动类型转换代码

4.2.2.2. getVariableLocal重载方法

方法签名

参数说明

作用域

典型使用场景

Object getVariableLocal(String taskId, String variableName)

taskId

：任务ID
variableName

：变量名

仅搜索当前任务作用域（Task Local Scope）

1. 仅需检查任务本地变量
2. 不确定变量类型时
3. 动态类型处理场景

<T> T getVariableLocal(String taskId, String variableName, Class<T> variableClass)

taskId

：任务ID
variableName

：变量名
variableClass

：目标类型类对象

仅搜索当前任务作用域（Task Local Scope）

1. 需要类型安全的变量访问
2. 直接获取特定类型的任务本地变量
3. 避免手动类型转换

4.3. 添加/更新任务变量

4.3.1. 特点：

支持多种Java类型，自动序列化存储。

4.3.2. 示例

4.3.2.1. 使用TaskService

taskService.setVariable(taskId, "newVar", "value");
// 或
taskService.setVariableLocal(taskId, "localVar", 100);
// 或taskService.setVariables(taskId, new HashMap<String, Object>() {{put("key1", "value");put("key2", 123);}});
// 或
taskService.setVariablesLocal(taskId, new HashMap<String, Object>() {{put("key1", "value");put("key2", 123);}});

方法签名	参数说明	作用域规则	变量存在性处理	典型使用场景
`void setVariable(String taskId, String variableName, Object value)`	`taskId` : 任务ID `variableName` : 变量名 `value` : 变量值	优先在现有作用域设置不存在时在最外层作用域(如流程实例)创建	更新现有变量或新建变量	1. 需要自动处理变量作用域 2. 单个变量设置
`void setVariables(String taskId, Map<String, ? extends Object> variables)`	`taskId` : 任务ID `variables` : 变量键值对集合	同setVariable规则，批量处理	批量更新/创建变量	1. 需要设置多个变量 2. 批量操作场景
`void setVariableLocal(String taskId, String variableName, Object value)`	`taskId` : 任务ID `variableName` : 变量名 `value` : 变量值	严格在任务本地作用域操作	只操作任务本地变量	1. 明确需要任务局部变量 2. 隔离变量作用域
`void setVariablesLocal(String taskId, Map<String, ? extends Object> variables)`	`taskId` : 任务ID `variables` : 变量键值对集合	严格在任务本地作用域批量操作	批量操作任务本地变量	1. 批量设置任务局部变量 2. 需要作用域隔离

4.3.2.2. 使用TaskRuntime

// 新增任务变量
taskRuntime.createVariable(new CreateTaskVariablePayload(taskId, "newVar", "value"));
// 更新任务变量
taskRuntime.updateVariable(new UpdateTaskVariablePayload(taskId, "newVar", "value"));

4.4. 删除任务变量

4.4.1. 特点：

删除所有（指定）变量，支持局部变量删除。

4.4.2. 示例

taskService.removeVariable(taskId, "existVar");
// 或
taskService.removeVariables(taskId,Arrays.asList("comment;linkTest".split(";")));
// 或
taskService.removeVariableLocal(taskId,"existVar");
// 或
taskService.removeVariablesLocal(taskId,Arrays.asList("comment;linkTest".split(";")));

5. 身份链接（IdentityLink）管理

5.1. 获取任务的所有身份链接

5.1.1. 特点

返回任务的所有用户/组关联关系。

5.1.2. 示例

5.1.2.1. 使用TaskService

taskService.getIdentityLinksForTask(taskId);

5.1.2.2. 使用TaskRuntime

taskRuntime.userCandidates(taskId);
taskRuntime.groupCandidates(taskId);

方法签名

参数说明

返回值说明

典型使用场景

List<String> userCandidates(String taskId)

taskId

：任务ID

返回该任务的所有候选用户ID列表
（格式如：["user1", "user2"]

）

1. 查询可处理任务的用户列表
2. 任务分配前的权限检查
3. 生成用户选择界面

List<String> groupCandidates(String taskId)

taskId

：任务ID

返回该任务的所有候选用户组ID列表
（格式如：["group1", "group2"]

）

1. 查询可处理任务的用户组
2. 基于组的任务分配
3. 批量权限管理

5.2. 在任务上创建身份链接

5.2.1. 特点

建立任务与用户/组的关联

5.2.2. 示例

5.2.2.1. 使用TaskService

taskService.addCandidateUser(taskId,"userId");
// 或
taskService.addCandidateGroup(taskId,"userGroup");
// 或
taskService.addUserIdentityLink(taskId,"userId", IdentityLinkType.ASSIGNEE);
// 或
taskService.addGroupIdentityLink(taskId,"userGroup",IdentityLinkType.PARTICIPANT);

5.2.2.1.1. 身份链接方法说明

方法签名	参数说明	作用	典型用例
`void addCandidateUser(String taskId, String userId)`	`taskId` : 任务ID `userId` : 用户ID	添加用户作为任务候选人	将用户加入可领取任务列表
`void addCandidateGroup(String taskId, String groupId)`	`taskId` : 任务ID `groupId` : 组ID	添加用户组作为任务候选组	让整个组的成员都能处理任务
`void addUserIdentityLink(String taskId, String userId, String identityLinkType)`	`taskId` : 任务ID `userId` : 用户ID `identityLinkType` : 链接类型	自定义用户任务关系	设置任务负责人/参与者
`void addGroupIdentityLink(String taskId, String groupId, String identityLinkType)`	`taskId` : 任务ID `groupId` : 组ID `identityLinkType` : 链接类型	自定义组任务关系	设置部门/业务单元关联

5.2.2.1.2. 身份链接类型说明

常量	类型	用途说明	适用方法示例
`ASSIGNEE`	用户	标记任务受托人（直接责任人）	`addUserIdentityLink(taskId, "user1", ASSIGNEE)`
`CANDIDATE`	用户/组	标记候选用户或组（可领取任务）	`addCandidateUser(taskId, "user2")`
`OWNER`	用户	标记任务所有者（管理权限）	`addUserIdentityLink(taskId, "user3", OWNER)`
`PARTICIPANT`	用户/组	标记任务参与者（协作权限）	`addGroupIdentityLink(taskId, "dept1", PARTICIPANT)`
`STARTER`	用户	系统自动标记流程发起人	通常由引擎自动设置

5.2.2.2. 使用TaskRuntime

taskRuntime.addCandidateGroups(new CandidateGroupsPayload(taskId, Collections.singletonList("userGroup")));
taskRuntime.addCandidateUsers(new CandidateUsersPayload(taskId, Collections.singletonList("userId")));

5.3. 删除任务上的身份链接

5.3.1. 特点

移除特定的身份关联

5.3.2. 示例

5.3.2.1. 使用TaskService

taskService.deleteCandidateUser(taskId,"userId");
taskService.deleteCandidateGroup(taskId,"userGroup");
taskService.deleteUserIdentityLink(taskId,"userId", IdentityLinkType.ASSIGNEE);
taskService.deleteGroupIdentityLink(taskId,"userGroup",IdentityLinkType.PARTICIPANT);

5.3.2.2. 使用TaskRuntime

taskRuntime.deleteCandidateGroups(new CandidateGroupsPayload(taskId, Collections.singletonList("userGroup")));
taskRuntime.deleteCandidateUsers(new CandidateUsersPayload(taskId, Collections.singletonList("userId")));

6. 评论（Comment）管理

6.1. 为任务创建新评论

6.1.1. 特点

为任务添加文字评论，记录处理意见。

6.1.2. 示例

taskService.addComment(taskId,processInstanceId,"审批通过");
taskService.addComment(taskId,processInstanceId,"APPROVAL","审批通过");

方法签名

参数说明

必填参数

默认值/自动处理

返回对象

典型使用场景

Comment addComment(taskId, processInstanceId, message)

taskId

: 关联任务ID
processInstanceId

: 关联流程实例ID
message

: 评论内容

message

必填
taskId

和processInstanceId

至少填一个

type

默认为 "comment"

Comment

对象（包含ID、时间、作者等信息）

添加普通文本评论

Comment addComment(taskId, processInstanceId, type, message)

type

: 评论类型（自定义分类）
其他参数同上

所有参数必填

无自动处理

Comment

对象

添加带分类的评论（如审批意见、系统日志等）

6.2. 查询任务评论

6.2.1. 特点

根据相关参数获取全部（特定）评论。

6.2.2. 示例

// 获取单个评论详情
Comment comment = taskService.getComment("comment001");
if (comment != null) {System.out.println(comment.getMessage());
}// 获取任务全部评论
List<Comment> taskComments = taskService.getTaskComments("task123");
taskComments.forEach(c -> System.out.println(c.getUserId() + ": " + c.getMessage()));// 获取任务的审批意见（自定义类型）
List<Comment> approvals = taskService.getTaskComments("task456", "APPROVAL");// 获取全系统错误日志
List<Comment> errorLogs = taskService.getCommentsByType("SYSTEM_ERROR");// 统计流程的人工评论数量
long humanComments = taskService.getProcessInstanceComments("proc789").stream().filter(c -> !c.getType().startsWith("SYSTEM_")).count();// 提取流程的系统自动评论
List<String> systemMessages = taskService.getProcessInstanceComments("proc101", "SYSTEM").stream().map(Comment::getMessage).collect(Collectors.toList());

方法签名	参数说明	返回值	查询范围	典型应用场景
`Comment getComment(commentId)`	`commentId` ：评论唯一ID	单个`Comment` 对象	全局查询	1. 精确获取特定评论 2. 评论详情展示
`List<Comment> getTaskComments(taskId)`	`taskId` ：任务ID	该任务所有评论列表	任务关联评论	1. 查看任务全部讨论记录 2. 任务历史追溯
`List<Comment> getTaskComments(taskId, type)`	`taskId` ：任务ID `type` ：评论类型	该任务指定类型的评论列表	任务关联评论+类型过滤	1. 筛选任务审批意见 2. 分离系统日志与人工评论
`List<Comment> getCommentsByType(type)`	`type` ：评论类型	全系统该类型评论列表	全局类型过滤	1. 统计所有审批记录 2. 系统日志审计
`List<Comment> getProcessInstanceComments(processInstanceId)`	`processInstanceId` ：流程实例ID	该流程所有评论列表	流程关联评论	1. 流程全局讨论记录 2. 流程运行监控
`List<Comment> getProcessInstanceComments(processInstanceId, type)`	`processInstanceId` ：流程实例ID `type` ：评论类型	该流程指定类型的评论列表	流程关联评论+类型过滤	1. 提取流程审批意见 2. 过滤流程系统消息

6.3. 删除任务的评论

6.3.1. 特点

删除已添加的相关评论

6.3.2. 示例

// 删除单条评论
taskService.deleteComment(commentId);// 删除特定任务的所有评论
taskService.deleteComments(taskId, null);// 删除特定流程实例的所有评论
taskService.deleteComments(null, processInstanceId);// 删除同时关联任务和流程实例的评论
taskService.deleteComments(taskId, processInstanceId);

方法签名

参数说明

删除范围

异常处理

典型应用场景

void deleteComments(taskId, processInstanceId)

taskId

：关联任务ID
processInstanceId

：关联流程实例ID

批量删除：
- 仅任务评论（processInstanceId=null）
- 仅流程评论（taskId=null）
- 两者交集评论（均非null）

参数全null时抛ActivitiIllegalArgumentException

1. 任务/流程数据清理
2. 敏感信息批量移除

void deleteComment(commentId)

commentId

：评论唯一ID

精确删除单条评论

评论不存在时抛ActivitiObjectNotFoundException

1. 特定评论撤回
2. 违规内容删除

7. 附件（Attachment）管理

7.1. 在任务上创建新附件(文件)

7.1.1. 特点：

上传文件作为任务附件

7.1.2. 示例

// 通过输入流上传文件
try (InputStream fileStream = new FileInputStream("report.pdf")) {Attachment attachment = taskService.createAttachment("DOCUMENT","taskId",null,"季度报告.pdf","2023年Q4销售数据",fileStream);
}// 通过URL添加附件
Attachment urlAttachment = taskService.createAttachment("LINK",null,"processInstanceId","产品官网","官方网站参考链接","https://product.com"
);

7.2. 获取任务的附件

7.2.1. 特点

返回任务的所有（部分）附件列表

7.2.2. 示例

// 获取任务附件列表
List<Attachment> taskFiles = taskService.getTaskAttachments("taskId");
taskFiles.forEach(att -> {System.out.println(att.getName());// 下载内容try (InputStream is = taskService.getAttachmentContent(att.getId())) {Files.copy(is, Paths.get("/downloads/" + att.getName()));}
});

7.3. 更新附件信息

7.3.1. 特点：

更新执行附件文件信息

7.3.2. 示例

// 更新附件描述
Attachment att = taskService.getAttachment("att456");
att.setDescription("更新版合同");
taskService.saveAttachment(att);

7.4. 删除附件信息

7.4.1. 特点

删除指定附件。

7.4.2. 示例

// 删除附件
taskService.deleteAttachment("att789");

7.5. 附件相关方法说明

方法类别	方法签名	参数说明	返回值/行为	典型应用场景
创建附件	`createAttachment(type, taskId, processInstanceId, name, description, content)`	`type` ：附件类型 `taskId` /`processInstanceId` ：至少一个非null `name` ：文件名 `description` ：描述 `content` ：输入流	返回新创建的`Attachment` 对象	上传本地文件作为附件
创建附件	`createAttachment(type, taskId, processInstanceId, name, description, url)`	`url` ：外部资源地址	返回新创建的`Attachment` 对象	链接外部资源作为附件
更新附件	`saveAttachment(attachment)`	`attachment` ：需更新的附件对象（需设置id）	无返回值	修改附件名称或描述
查询附件	`getAttachment(attachmentId)`	`attachmentId` ：附件唯一ID	返回`Attachment` 对象（不存在时返回null）	获取附件元数据
	`getAttachmentContent(attachmentId)`	`attachmentId` ：附件唯一ID	返回`InputStream` （需手动关闭）	下载附件内容
	`getTaskAttachments(taskId)`	`taskId` ：任务ID	返回附件列表（可能为空）	查看任务所有附件
	`getProcessInstanceAttachments(processInstanceId)`	`processInstanceId` ：流程实例ID	返回附件列表（可能为空）	查看流程所有附件
删除附件	`deleteAttachment(attachmentId)`	`attachmentId` ：附件唯一ID	无返回值	移除无效附件