【08】Camunda7-历史记录

AlieNeny

已于 2024-05-05 19:15:50 修改

阅读量1.2k

点赞数 17

分类专栏： Camunda 文章标签： camunda camunda7 流程引擎历史记录

于 2024-05-02 07:31:41 首次发布

本文链接：https://blog.csdn.net/AlieNeny/article/details/138386422

版权

Camunda 专栏收录该内容

26 篇文章 5 订阅

订阅专栏

历史记录事件流提供了有关已执行的流程实例的审核信息。

流程引擎将维护数据库中正在运行的流程实例的状态。这包括writing（1），当流程实例进入等待状态时，写流程实例状态到数据库；reading(2)，当流程执行继续时，读取流程实例的状态。我们称这个数据库为运行时数据库。

除了维护运行时状态外，流程引擎还会创建一个审计日志，提供有关已执行的流程实例的审计信息。我们将此事件流称为历史记录事件流（3），组成此事件流的各个事件称为历史事件，并包含有关已执行的流程实例、活动实例、已更改的流程变量等的数据。在默认配置中，流程引擎将简写此事件流到历史数据库，且可通过历史服务API允许查询此数据库。

历史数据库和历史服务是可选组件；如果历史事件流没有记录到历史数据库，或者如果用户选择将事件记录到其他数据库，那么流程引擎仍然能够工作，并且仍然能够填充历史事件流。因为BPMN 2.0核心引擎组件没有从历史记录数据库中读取状态。也可以使用流程引擎配置中的历史级别设置来配置所记录的数据量。

由于流程引擎不依赖于历史数据库的存在来生成历史事件流，因此可以提供不同的后端服务来处理、存储历史事件流。默认的后端服务是DbHistoryEventHandler ，它将事件流记录到历史数据库中。同时，也可以交替换默认的后端服务，并为历史事件日志提供一个自定义存储机制。

历史记录级别

历史记录级别控制流程引擎通过历史记录事件流提供的数据量。可提供以下设置：

历史外部任务日志，其中包含关于外部日志的信息。该日志提供了有关外部任务的生命周期的详细信息。

历史流程实例状态

None(无历史记录)：未触发任何历史记录事件。
ACTIVITY：将触发以下事件：
- 流程实例启动、更新、结束、迁移：在流程实例正在启动、更新、结束和迁移时触发
- 案例实例创建、更新、关闭：在创建、更新和关闭案例实例时触发
- 活动实例启动、更新、结束、迁移：在活动实例正在启动、更新、结束和迁移时触发
- 案例活动实例创建、更新、结束：在创建、更新和结束时触发
- 任务实例创建、更新、完成、删除、迁移：在任务实例被创建、更新时触发（即重新分配、委托等），已完成、删除和迁移。
AUDIT(审核)：除历史记录级别活动提供的事件外，还将触发以下事件：
- 变量实例的创建、更新、删除、迁移：在创建、更新、删除和迁移流程变量时触发。默认历史后端（Db历史evendler）将变量实例事件写入历史变量实例数据库表。此表中的行将随着变量实例的更新而更新，这意味着只有流程变量的最后一个值可用。
FULL(完整)：除历史记录级审核提供的事件外，还将触发以下事件：
- 表单属性更新：在创建和/或更新表单属性时触发。
- 默认的历史记录后端（Db历史事件处理程序）将历史变量更新写入数据库。这使得使用历史记录服务检查流程变量的中间值成为可能。
- 用户操作日志更新：当用户执行诸如声明用户任务、委派用户任务等操作时触发。
- 事件创建、删除、解决、迁移：在创建、删除、解决和迁移事件时触发
- 历史作业日志创建、失败、成功、删除：在创建作业时触发、作业执行失败或成功或作业被删除
- 决策实例评估：当DMN引擎评估决策时触发。
- 批开始，结束：在正在开始和结束批时触发
- 身份链接添加、删除：当添加、删除或设置或更改用户任务的受让人以及设置或更改用户任务的所有者时触发。
- 历史外部任务日志创建、删除、失败、成功：在创建、删除或报告外部任务执行失败或成功时触发。
AUTO(自动)：如果您计划在同一个数据库上运行多个引擎，则该级别自动是非常有用的。在这种情况下，所有的引擎都必须使用相同的历史记录级别。使用自动同步，引擎自动确定数据库中已经配置的级别。如果没有找到，则使用默认值审核。请记住：如果您计划使用自定义历史记录级别，则必须为每个配置注册自定义级别，否则将抛出异常。
如果需要自定义所记录的历史事件的数量，可以提供一个自定义的HistoryEventProducer，并将其连接在流程引擎配置中。
历史记录级别可以作为流程引擎配置中的一个属性来提供。根据流程引擎的配置方式，可以使Java代码来设置该属性：
```
ProcessEngine processEngine = ProcessEngineConfiguration
  .createProcessEngineConfigurationFromResourceDefault()
  .setHistory(ProcessEngineConfiguration.HISTORY_FULL)
  .buildProcessEngine();
```
它还可以使用Spring XML或部署描述符（bpm-platform.xml，processes.xml）进行设置。需要注意，当使用默认的历史记录后端时，历史记录级别将存储在数据库中，并且以后不能再更改。一般情况下，应用程序的历史记录级别最好设置为FULL，“较低”的历史级别将禁用某些与历史相关的功能。
默认的历史数据库服务
默认的history database会将历史记录事件写入到相应的数据库表中。然后，可以使用历史记录服务或使用REST API来查询数据库表。
历史实体
有以下的历史记录实体，与运行时数据相比，在流程和案例实例完成后，这些实体也将仍然存在于数据库中：
历史流程实例：包含有关当前和过去的流程实例的信息。
历史变量实例：包含关于流程实例中保存的变量的最新状态的信息。
历史案例实例：其中包含关于当前和过去的案例实例的信息。
历史活动实例：包含有关单个活动执行的信息的实例。
历史案例活动实例：包含单个执行的信息。
历史任务实例：包含关于当前和过去（已完成和已删除）任务实例的信息。
历史记录详细信息：其中包含与历史流程实例、活动实例或任务实例相关的各种信息。
历史事件：包含有关当前和过去（即已删除或已解决）事件的信息的历史事件。
用户操作日志输入日志条目：其中包含有关用户执行的操作的信息。这用于记录操作，如创建新任务、完成任务等。
历史作业日志：包含有关作业执行的信息。该日志提供了有关作业生命周期的详细信息。
历史决策实例：包含关于一个决策的单个评估的信息，包括输入值和输出值。
包含当前和过去批次的信息的历史批。
历史标识链接日志包含有关当前和过去（添加、删除、受让人设置或更改以及所有者设置或更改）标识链接的信息。

对于每个流程实例，流程引擎将在历史数据库中创建单个记录，并将在流程执行期间不断更新该记录。每个历史流程实例记录都可以获得以下指定的状态之一：

ACTIVE-正在活动中运行的流程实例
SUSPENDED -挂起的流程实例
COMPLETED-已完成-通过正常的结束事件，已完成
EXTERNALLY_TERMINATED -在外部终止，例如通过REST API
INTERNALLY_TERMINATED -在内部终止，例如通过终止边界事件

其中以下状态可以在外部触发，通过REST API或Cockpit：ACTIVE, SUSPENDED, EXTERNALLY_TERMINATED。

历史查询

HistoryService 提供了以下方法，完整描述可以在org.camunda.bpm.engine.history中查看。

createHistoricProcessInstanceQuery()
createHistoricVariableInstanceQuery()
createHistoricCaseInstanceQuery()
createHistoricActivityInstanceQuery()
createHistoricCaseActivityInstanceQuery()
createHistoricDetailQuery()
createHistoricTaskInstanceQuery()
createHistoricIncidentQuery()
createUserOperationLogQuery()
createHistoricJobLogQuery()
createHistoricDecisionInstanceQuery()
createHistoricBatchQuery()
createHistoricExternalTaskLogQuery()
createHistoricIdentityLinkLogQuery()

HistoricProcessInstanceQuery：获取在流程定义为“XXX”的所有已完成流程实例中，已完成时间最长（持续时间最长）的十个历史流程实例。

historyService.createHistoricProcessInstanceQuery()
  .finished()
  .processDefinitionId("XXX")
  .orderByProcessInstanceDuration().desc()
  .listPage(0, 10);

HistoricActivityInstanceQuery：针对流程实例中ID为“XXX”的流程实例，获取类型为servicetask的一个最近完成的历史活动实例。

historyService.createHistoricActivityInstanceQuery()
  .activityType("serviceTask")
  .processDefinitionId("XXX")
  .finished()
  .orderByHistoricActivityInstanceEndTime().desc()
  .listPage(0, 1);

HistoricVariableInstanceQuery：获取流程实例ID为“XXX”的已完成流程实例中的全部历史变量实例，并按变量名称排序。

historyService.createHistoricVariableInstanceQuery()
  .processInstanceId("XXX")
  .orderByVariableName().desc()
  .list();

HistoricBatchQuery：获取所有历史流程实例的迁移批量并按ID排序。

historyService.createHistoricBatchQuery()
  .type(Batch.TYPE_PROCESS_INSTANCE_MIGRATION)
  .orderById().desc()
  .list();

历史报表

可以使用reports section来检索自定义统计信息和报表。目前，支持以下几种报告：

Instance Duration Report
Task Report
Finished Instance Report

Instance Duration Report

检索有关已完成流程实例的“持续时间”相关的报告，并按指定的期间进行分组。这些报告包括在指定的期间内开始的所有已完成的流程实例的最长、最小和平均持续时间。org.camunda.bpm.engine.query.PeriodUnit目前支持MONTH和QUARTER ，以下代码示例检索自引擎启动以来每个月的报告：

historyService
  .createHistoricProcessInstanceReport()
  .duration(PeriodUnit.MONTH);

如果想缩小时间范围，可以使用以下方法：

startedBefore: 只考虑在给定日期之前启动的历史流程实例.
startedAfter: 只考虑在给定日期之后开始的历史流程实例.
processDefinitionIdIn: 只考虑给定的历史流程实例.
processDefinitionKeyIn: 只考虑给定流程定义键的历史流程实例.

Calendar calendar = Calendar.getInstance();
historyService.createHistoricProcessInstanceReport()
  .startedBefore(calendar.getTime())
  .duration(PeriodUnit.MONTH);

Task Report

检索已完成任务的报表。对于Task Report有两种报表类型：计数和持续时间。

如果在报表查询末尾使用countByProcessDefinitionKey 或countByTaskName，则报表包含已完成任务计数列表，其中条目包含任务名称、任务的定义键、流程定义Id、流程定义键、流程定义名称以及在给定期间内指定键完成的任务计数。countByProcessDefinitionKey 和countByTaskName根据条件“定义键”或“任务名称”对计数报告进行分组。示例代码如下：

historyService
  .createHistoricTaskInstanceReport()
  .countByTaskName();

如果报表类型设置为持续时间，则报表包含给定期间内所有已完成任务实例的最小、最大和平均持续时间值。

historyService
  .createHistoricTaskInstanceReport()
  .duration(PeriodUnit.MONTH);

Finished Instance Report

检索已完成的流程、决策或案例实例的报表。该报告帮助用户调整流程定义的历史记录生存时间。这可以看到历史数据的摘要，并可以在历史清理后进行清理。该报表输出字段是流程定义id、键、名称、版本、已完成实例的计数和“可清理”实例的计数。

historyService
  .createHistoricFinishedProcessInstanceReport()
  .list();

historyService
  .createHistoricFinishedDecisionInstanceReport()
  .list();

historyService
  .createHistoricFinishedCaseInstanceReport()
  .list();

自定义的历史记录后端服务

每当更改运行时实体的状态时，流程引擎的核心执行组件都会触发历史记录事件。为了使这更灵活，历史事件的实际创建以及使用来自运行时结构的数据填充历史事件都被委托给“History Event Producer-历史事件生成者”。生成者将进入运行时数据结构（如执行实体或任务实体），创建一个新的历史记录事件，并使用从运行时结构中提取的数据填充它。

该事件接下来被传递到构成历史记录后端的历史记录事件处理程序（History Event Handler）。上图包含一个事件传输（event transport）逻辑组件，它是生成事件的流程引擎核心组件和历史记录事件处理程序之间的通道。在默认实现中，事件将在同一JVM中同步地传递给历史记录事件处理程序。然而，从概念上讲，可以将事件流发送到不同的JVM（可能运行在不同的机器上），并使传递成为异步的。一个很好的匹配方法可能是一个事务性消息队列（JMS）。

一旦事件到达历史事件处理程序，就可以处理并存储在某种数据存储中。默认的实现是将事件写入历史数据库（表），以便可以使用历史记录服务来查询它们。使用自定义历史记录事件处理程序，需要执行两个主要步骤：

提供一个历史事件处理程序接口的自定义实现。
在流程引擎配置中连接自定义实现。

Composite History Handling。请注意，如果提供了历史事件处理程序的自定义实现，并将其连接到流程引擎，则将覆盖默认的数据库历史事件处理程序。其结果是，流程引擎将停止写数据到历史数据库（表），并且也将无法使用历史记录服务来查询审计日志。如果不想替换默认行为，而只提供了一个额外的事件处理程序，则可以使用类org.camunda.bpm.engine.impl.history.handler.CompositeHistoryEventHandler ，它用来向多个事件处理程序组成的集合分派事件。

此外，如果要覆盖默认的Db历史事件处理程序，则必须显式地将enableDefaultDbHistoryEventHandler引擎配置属性设置为false。