createHistoricVariableInstanceQuery

Flowable 7.1.0 摘要：创建历史变量实例查询对象，用于查询流程变量的历史值。

方法签名与说明

HistoricVariableInstanceQuery createHistoricVariableInstanceQuery()

创建历史变量实例查询构建器。可以查询流程执行过程中所有变量的历史值，包括已删除的变量。

Returns:

• HistoricVariableInstanceQuery - 历史变量实例查询构建器

常见使用场景

1. 数据追溯

追溯流程变量的历史值，了解数据变更过程。

2. 审计合规

审计人员查看流程中关键数据的变更历史。

3. 问题排查

排查流程问题时，查看变量的历史值帮助定位问题。

Kotlin + Spring Boot 调用示例

示例1：查询流程实例的所有变量历史

import org.flowable.engine.HistoryService
import org.springframework.stereotype.Service

@Service
class ProcessVariableHistoryService(
    private val historyService: HistoryService
) {
    
    /**
     * 查询流程实例的变量历史
     * 企业场景：查看请假申请的所有表单数据
     */
    fun getProcessVariables(processInstanceId: String): List<Map<String, Any?>> {
        val variables = historyService.createHistoricVariableInstanceQuery()
            .processInstanceId(processInstanceId)
            .list()
        
        return variables.map { variable ->
            mapOf(
                "variableName" to variable.variableName,
                "variableType" to variable.variableTypeName,
                "value" to variable.value,
                "createTime" to variable.createTime,
                "lastUpdatedTime" to variable.lastUpdatedTime
            )
        }
    }
}

示例2：查询特定变量的历史

import org.flowable.engine.HistoryService
import org.springframework.stereotype.Service

@Service
class VariableTraceService(
    private val historyService: HistoryService
) {
    
    /**
     * 查询特定变量的历史值
     * 企业场景：追踪请假天数的变更历史
     */
    fun getVariableHistory(processInstanceId: String, variableName: String): Any? {
        val variable = historyService.createHistoricVariableInstanceQuery()
            .processInstanceId(processInstanceId)
            .variableName(variableName)
            .singleResult()
        
        return variable?.value
    }
}

示例3：审计关键变量变更

import org.flowable.engine.HistoryService
import org.springframework.stereotype.Service
import java.util.Date

data class VariableAudit(
    val processInstanceId: String,
    val variableName: String,
    val value: Any?,
    val createTime: Date?,
    val lastUpdatedTime: Date?
)

@Service
class VariableAuditService(
    private val historyService: HistoryService
) {
    
    /**
     * 审计关键变量
     * 企业场景：审计采购金额的变更记录
     */
    fun auditKeyVariables(
        processDefinitionKey: String,
        variableName: String
    ): List<VariableAudit> {
        
        val variables = historyService.createHistoricVariableInstanceQuery()
            .processDefinitionKey(processDefinitionKey)
            .variableName(variableName)
            .list()
        
        return variables.map { v ->
            VariableAudit(
                processInstanceId = v.processInstanceId,
                variableName = v.variableName,
                value = v.value,
                createTime = v.createTime,
                lastUpdatedTime = v.lastUpdatedTime
            )
        }
    }
}

示例4：REST API

import org.flowable.engine.HistoryService
import org.springframework.web.bind.annotation.*

@RestController
@RequestMapping("/api/history/variables")
class HistoricVariableController(
    private val historyService: HistoryService
) {
    
    @GetMapping("/process-instance/{processInstanceId}")
    fun getVariables(@PathVariable processInstanceId: String): List<Map<String, Any?>> {
        val variables = historyService.createHistoricVariableInstanceQuery()
            .processInstanceId(processInstanceId)
            .list()
        
        return variables.map { mapOf(
            "name" to it.variableName,
            "type" to it.variableTypeName,
            "value" to it.value
        )}
    }
}

注意事项

1. 变量类型

• 支持多种类型：String, Integer, Boolean, Date, JSON等
• 复杂对象会被序列化存储

2. 性能考虑

• 添加流程实例ID过滤，提高查询效率
• 大数据量时使用分页

3. 变量删除

• 即使变量被删除，历史记录仍然保留

相关 API

• HistoryService.createHistoricVariableInstanceQuery() - 查询历史变量
• HistoryService.createHistoricDetailQuery() - 查询历史详情
• HistoryService.createHistoricProcessInstanceQuery() - 查询流程历史

本文档说明

• 基于 Flowable 7.1.0 版本编写
• 所有示例均可直接在 Spring Boot + Kotlin 项目中使用