【Activiti7】04 - History Service

Activiti - History Service

HistoryService是Activiti的历史管理类服务，提供流程相关的历史数据管理，如历史流程实例、历史活动和历史流程任务的查询等。

本文旨在介绍HistoryService在开发中的常用功能。

1. 获取HistoryService

使用示例：

@Test
public void testGetHistoryService() {
    // 1.获取引擎
    ProcessEngine processEngine = ProcessEngines.getDefaultProcessEngine();
    // 2.获取HistoryService
    HistoryService historyService = processEngine.getHistoryService();
    // ...
}

2. 历史流程实例查询

HistoryService提供正在进行的以及已经完成的流程实例相关的信息。Activiti对历史数据表进行了优化以便于提高查询的性能，而且除HistoryService以外的服务都无法删除历史数据表中的记录。

曾经执行的或者正在执行的流程实例会被HistoryService记录并存放在历史数据表中。通过流程实例的id或者名称等信息就可以查询到表中该流程实例相关的信息。

API声明	参数与功能
HistoricProcessInstanceQuery createHistoricProcessInstanceQuery();	创建一个历史流程实例查询对象

使用示例：

/**
 * 根据流程定义查询其上的历史流程实例
 */
@Test
public void queryHistoricProcessInstance(){
    // 查询流程定义Key为"activiti_key"的流程定义
    String  processDefinitionKey = "activiti_key"; 
    List<HistoricProcessInstance> historicProcessInstanceList =
        // 创建历史流程实例查询对象
        historyService.createHistoricProcessInstanceQuery() 
        // 查询该流程定义上，历史中所有的流程实例
        .processDefinitionKey(processDefinitionKey)
        // 按照流程实例结束的时间排序
        .orderByProcessInstanceEndTime()
        .desc()
        .list();
	
    // 输出查询结果
    for(HistoricProcessInstance historicProcessInstance:historicProcessInstanceList){
        System.out.println("历史流程实例id："+historicProcessInstance.getId());
        System.out.println("历史流程实例结束时间："+historicProcessInstance.getEndTime());
    }
}

历史流程查询相关的表

• ACT_HI_ACTINST表中储存了历史的流程实例和流程活动相关的信息。
  1. PROC_DEF_ID_：流程定义ID，组成规则为【流程定义KEY:版本号:自增长ID】
  2. PROC_INST_ID_：流程实例ID
  3. ACT_ID_：BPMN中定义的任务ID
  4. ACT_NAME_：BPMN中定义的任务名称
  5. ASSIGNEE_：BPMN中定义的负责人
  6. START_TIME_：活动开始的时间
  7. END_TIME_：活动结束的时间

3. 历史活动查询

除了查询历史流程实例以外，HistoryService还提供了查询某个实例所有历史活动的功能。实例在运行过程中会遇到任务节点，除此之外，流程实例的启动与结束也会被记录在流程实例的历史活动中。

通过使用流程实例id查询等方式，可以获取到该实例相关的所有历史活动。

API声明	参数与功能
HistoricActivityInstanceQuery createHistoricActivityInstanceQuery();	创建一个历史活动查询对象

使用示例：

/**
 * 查询某个流程实例经历的所有历史活动
 */
@Test
public void queryHistoricActivityInstance(){
    // 查询id为3002的流程实例相关的活动
    String  processInstanceId = "3002";
    List<HistoricActivityInstance> historicProcessInstanceList =
        // 创建历史活动查询对象
        historyService.createHistoricActivityInstanceQuery() 
        // 查询流程实例id相关的活动
        .processInstanceId(processInstanceId)
        // 筛选活动类型为userTask
        .activityType("userTask") 
        .list();

    for(HistoricActivityInstance historicActivityInstance:historicProcessInstanceList){
        System.out.println("历史活动id："+historicActivityInstance.getId());
        System.out.println("历史活动名称："+historicActivityInstance.getActivityName());
        System.out.println("历史活动代理人："+historicActivityInstance.getAssignee());
    }
}

历史活动查询相关的表

• ACT_HI_ACTINST表中储存了历史的流程实例和流程活动相关的信息。
  1. PROC_DEF_ID_：流程定义ID，组成规则为【流程定义KEY:版本号:自增长ID】
  2. PROC_INST_ID_：流程实例ID
  3. ACT_ID_：BPMN中定义的任务ID
  4. ACT_NAME_：BPMN中定义的任务名称
  5. ASSIGNEE_：BPMN中定义的负责人
  6. START_TIME_：活动开始的时间
  7. END_TIME_：活动结束的时间

4. 历史任务查询

相比于历史活动，历史流程任务并不包含流程实例的开始与结束，仅包含流程定义中的任务节点。

API声明	参数与功能
HistoricTaskInstanceQuery createHistoricTaskInstanceQuery();	创建一个历史任务查询对象

使用示例：

/**
 * 根据办理人查看历史流程任务
 */
@Test
public void queryHistoricTaskInstance(){
    String  processDefinitionKey = "activit_key";
    String assignee = "代理人张三";
    List<HistoricTaskInstance> historicTaskInstanceList =
        historyService.createHistoricTaskInstanceQuery()
        // 根据流程定义ID查询其上的任务
        .processDefinitionKey(processDefinitionKey)
        // 选取负责人为"代理人张三"的任务
        .taskAssignee(assignee)
        .list();

    for(HistoricTaskInstance historicTaskInstance:historicTaskInstanceList){
        System.out.println("历史任务id："+historicTaskInstance.getId());
        System.out.println("历史活动名称："+historicTaskInstance.getName());
        System.out.println("历史活动结束时间："+historicTaskInstance.getEndTime());
        System.out.println("历史活动办理人："+historicTaskInstance.getAssignee());
    }
}

历史任务查询相关的表

• ACT_HI_TASKINST表中储存了历史的流程实例和任务相关的信息。
  1. PROC_DEF_ID_：流程定义ID，组成规则为【流程定义KEY:版本号:自增长ID】
  2. PROC_INST_ID_：流程实例ID
  3. TASK_DEF_KEY_：BPMN中定义的任务ID
  4. NAME_：BPMN中定义的任务名称
  5. ASSIGNEE_：BPMN中定义的负责人
  6. START_TIME_：活动开始的时间
  7. END_TIME_：活动结束的时间

5. 历史流程变量查询

HistoryService还提供了查询历史流程变量的功能。

示例中通过查询流程实例的id，查询到了对应的流程变量信息。

API声明	参数与功能
HistoricVariableInstanceQuery createHistoricVariableInstanceQuery();	创建一个历史流程变量查询对象

使用示例：

/**
 * 根据流程实例的ID查看历史流程变量
 */
@Test
public void queryHistoricVariableInstance(){
    String  processInstanceId = "3002";
    List<HistoricVariableInstance> historicVariableInstanceList =
            historyService.createHistoricVariableInstanceQuery()
                    .processInstanceId(processInstanceId)
                    .list();
 
    for(HistoricVariableInstance historicVariableInstance:historicVariableInstanceList){
        System.out.println("流程变量id："+historicVariableInstance.getId());
        System.out.println("流程变量名："+historicVariableInstance.getVariableName());
        System.out.println("流程变量值："+historicVariableInstance.getValue());
    }
}

历史流程变量查询相关的表

• ACT_HI_VARINST表中储存了历史的流程实例和流程变量相关的信息。
  1. PROC_INST_ID_：流程实例ID
  2. NAME_：流程变量名称
  3. VAR_TYPE_：变量数据类型
  4. BYTEARRAY_ID_：变量对应于ACT_GE_BYTEARRAY表中的主键
  5. CREATE_TIME_：变量创建时间
  6. LAST_UPDATED_TIME_：最近一次更新的时间

API声明源代码及注释

/*
 * Copyright 2010-2020 Alfresco Software, Ltd.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */


package org.activiti.engine;

import java.util.List;

import org.activiti.engine.api.internal.Internal;
import org.activiti.engine.history.HistoricActivityInstance;
import org.activiti.engine.history.HistoricActivityInstanceQuery;
import org.activiti.engine.history.HistoricDetail;
import org.activiti.engine.history.HistoricDetailQuery;
import org.activiti.engine.history.HistoricIdentityLink;
import org.activiti.engine.history.HistoricProcessInstance;
import org.activiti.engine.history.HistoricProcessInstanceQuery;
import org.activiti.engine.history.HistoricTaskInstance;
import org.activiti.engine.history.HistoricTaskInstanceQuery;
import org.activiti.engine.history.HistoricVariableInstance;
import org.activiti.engine.history.HistoricVariableInstanceQuery;
import org.activiti.engine.history.NativeHistoricActivityInstanceQuery;
import org.activiti.engine.history.NativeHistoricDetailQuery;
import org.activiti.engine.history.NativeHistoricProcessInstanceQuery;
import org.activiti.engine.history.NativeHistoricTaskInstanceQuery;
import org.activiti.engine.history.NativeHistoricVariableInstanceQuery;
import org.activiti.engine.history.ProcessInstanceHistoryLog;
import org.activiti.engine.history.ProcessInstanceHistoryLogQuery;
import org.activiti.engine.task.IdentityLink;

/**
 * Service exposing information about ongoing and past process instances. This is different from the runtime information in the sense that this runtime information only contains the actual runtime
 * state at any given moment and it is optimized for runtime process execution performance. The history information is optimized for easy querying and remains permanent in the persistent storage.
 *
 */
@Internal
public interface HistoryService {

  /**
   * Creates a new programmatic query to search for {@link HistoricProcessInstance}s.
   */
  HistoricProcessInstanceQuery createHistoricProcessInstanceQuery();

  /**
   * Creates a new programmatic query to search for {@link HistoricActivityInstance}s.
   */
  HistoricActivityInstanceQuery createHistoricActivityInstanceQuery();

  /**
   * Creates a new programmatic query to search for {@link HistoricTaskInstance}s.
   */
  HistoricTaskInstanceQuery createHistoricTaskInstanceQuery();

  /** Creates a new programmatic query to search for {@link HistoricDetail}s. */
  HistoricDetailQuery createHistoricDetailQuery();

  /**
   * Returns a new {@link org.activiti.engine.query.NativeQuery} for process definitions.
   */
  NativeHistoricDetailQuery createNativeHistoricDetailQuery();

  /**
   * Creates a new programmatic query to search for {@link HistoricVariableInstance}s.
   */
  HistoricVariableInstanceQuery createHistoricVariableInstanceQuery();

  /**
   * Returns a new {@link org.activiti.engine.query.NativeQuery} for process definitions.
   */
  NativeHistoricVariableInstanceQuery createNativeHistoricVariableInstanceQuery();

  /**
   * Deletes historic task instance. This might be useful for tasks that are {@link TaskService#newTask() dynamically created} and then {@link TaskService#complete(String) completed}. If the historic
   * task instance doesn't exist, no exception is thrown and the method returns normal.
   */
  void deleteHistoricTaskInstance(String taskId);

  /**
   * Deletes historic process instance. All historic activities, historic task and historic details (variable updates, form properties) are deleted as well.
   */
  void deleteHistoricProcessInstance(String processInstanceId);

  /**
   * creates a native query to search for {@link HistoricProcessInstance}s via SQL
   */
  NativeHistoricProcessInstanceQuery createNativeHistoricProcessInstanceQuery();

  /**
   * creates a native query to search for {@link HistoricTaskInstance}s via SQL
   */
  NativeHistoricTaskInstanceQuery createNativeHistoricTaskInstanceQuery();

  /**
   * creates a native query to search for {@link HistoricActivityInstance}s via SQL
   */
  NativeHistoricActivityInstanceQuery createNativeHistoricActivityInstanceQuery();

  /**
   * Retrieves the {@link HistoricIdentityLink}s associated with the given task. Such an {@link IdentityLink} informs how a certain identity (eg. group or user) is associated with a certain task (eg.
   * as candidate, assignee, etc.), even if the task is completed as opposed to {@link IdentityLink}s which only exist for active tasks.
   */
  List<HistoricIdentityLink> getHistoricIdentityLinksForTask(String taskId);

  /**
   * Retrieves the {@link HistoricIdentityLink}s associated with the given process instance. Such an {@link IdentityLink} informs how a certain identity (eg. group or user) is associated with a
   * certain process instance, even if the instance is completed as opposed to {@link IdentityLink}s which only exist for active instances.
   */
  List<HistoricIdentityLink> getHistoricIdentityLinksForProcessInstance(String processInstanceId);

  /**
   * Allows to retrieve the {@link ProcessInstanceHistoryLog} for one process instance.
   */
  ProcessInstanceHistoryLogQuery createProcessInstanceHistoryLogQuery(String processInstanceId);

}