A
📖 Wiki
中

公文流转与 jBPM 工作流

📄 业务模块 43 min read 81 views Updated 2026-10-25 Chinese only

导读

关于「公文流转与 jBPM 工作流」,这里按「结论 → 原理 → 追问」的顺序梳理,方便随时查阅。

公文流转是 OA 的核心。这一篇讲清楚:jBPM 是什么、怎么集成进来、公文如何与流程实例绑定、审批如何驱动流程前进,以及那个很妙的设计——用流程变量驱动分支条件。


一、jBPM 核心概念

概念 对应类 含义
流程定义 ProcessDefinition 一张流程图(XML),可有多个版本
流程实例 ProcessInstance 某份公文的一次实际流转
令牌 Token 当前所处节点的位置指针
节点 Node / TaskNode / StartState / EndState / Fork / Join 流程中的步骤
流向 Transition 节点之间的连线,可带条件
任务实例 TaskInstance 分配给某个人的待办
流程变量 ContextInstance 挂在流程实例上的数据(如公文 ID)
上下文 JbpmContext jBPM 的门面对象,所有操作的入口

关键 API 入口:

JbpmContext context = jbpmConfiguration.createJbpmContext();
context.getGraphSession()       // 流程定义/实例的增删查
context.getTaskMgmtSession()    // 任务实例查询
context.getProcessInstance(id)  // 取流程实例

二、集成 jBPM 的三步

第 1 步:让 jBPM 的表建起来

  1. 拷贝依赖 jar 到 WEB-INF/lib:jbpm-jpdl.jar、jbpm-identity.jar、bsh.jar、jcr-1.0.jar 及 jboss 相关包;
  2. 在 hibernate.cfg.xml 中加入 jBPM 的映射资源:
<mapping resource="org/jbpm/graph/action/Script.hbm.xml"/>
<mapping resource="org/jbpm/identity/User.hbm.xml"/>
<mapping resource="org/jbpm/identity/Group.hbm.xml"/>
<mapping resource="org/jbpm/identity/Membership.hbm.xml"/>
<mapping resource="org/jbpm/db/hibernate.queries.hbm.xml"/>
<!-- 其余 jbpm 映射文件见 jbpm-jpdl.jar -->

同时开启二级缓存(jBPM 要求):

<property name="hibernate.cache.provider_class">org.hibernate.cache.HashtableCacheProvider</property>
  1. 类名冲突处理:jBPM 自带 org.jbpm.identity.User,与 OA 的 com.oa.model.User 重名,Hibernate 的自动导入会报 Duplicate import 错误。解决方式是把业务 User 的映射关掉自动导入:
<hibernate-mapping auto-import="false">
  <class name="com.oa.model.User" table="T_User"> ... </class>
</hibernate-mapping>

代价是:此后所有 HQL 中引用 User 都必须写全限定类名:

getHibernateTemplate().find("from com.oa.model.User u where u.username = ?", username);
  1. 启动 Tomcat,应能看到 JBPM_* 系列表被创建。

第 2 步:与 Spring 整合

引入 spring-modules-jbpm31.jar(来自 spring-modules-0.8),把 JbpmConfiguration 交给 Spring:

<bean id="jbpmConfiguration"
      class="org.springmodules.workflow.jbpm31.LocalJbpmConfigurationFactoryBean">
    <property name="configuration" value="classpath:jbpm.cfg.xml"/>
</bean>

jbpm.cfg.xml 从 jBPM 发行包的 src/jpdl/org/jbpm/default.jbpm.cfg.xml 拷贝改名即可,核心是指定 persistence 服务与 hibernate 配置位置:

<jbpm-configuration>
  <jbpm-context>
    <service name="persistence" factory="org.jbpm.persistence.db.DbPersistenceServiceFactory"/>
    <service name="tx"          factory="org.jbpm.tx.TxServiceFactory"/>
    <service name="message"     factory="org.jbpm.msg.db.DbMessageServiceFactory"/>
    <service name="scheduler"   factory="org.jbpm.scheduler.db.DbSchedulerServiceFactory"/>
    <service name="logging"     factory="org.jbpm.logging.db.DbLoggingServiceFactory"/>
    <service name="authentication" factory="org.jbpm.security.authentication.DefaultAuthenticationServiceFactory"/>
  </jbpm-context>
  <string name="resource.hibernate.cfg.xml" value="hibernate.cfg.xml"/>
  ...
</jbpm-configuration>

第 3 步:业务类共享同一个 Session

这是最关键的一步:jBPM 与业务数据必须在同一事务里,否则会出现"公文保存了但流程没动"的脏数据。

private JbpmContext getContext() {
    JbpmContext context = jbpmConfiguration.createJbpmContext();
    context.setSession(getSession());   // 复用 Spring 管理的当前 Hibernate Session
    return context;
}

getSession() 来自 HibernateDaoSupport,拿到的正是当前线程绑定、被事务管理的 Session。


三、业务模型

public class Workflow {
    private int id;
    private String name;               // 流程名称,与 jBPM 中的流程定义名一致
    private byte[] processDefinition;  // 流程定义 XML
    private byte[] processImage;       // 流程图(jpg)
}

public class Document {
    public final static String STATUS_NEW = "新建";
    public final static String STATUS_END = "完成";

    private int id;
    private String title;
    private String description;
    private byte[] content;            // 公文正文附件
    private User creator;              // 创建人
    private Date createTime;
    private Workflow workflow;         // 使用的流程定义
    private long processInstanceId;    // 对应的 jBPM 流程实例 ID
    private String status;             // 当前所处节点名,或"完成"
    private Map props;                 // 动态表单的值
}

public class ApproveInfo {
    private int id;
    private String comment;      // 审批意见
    private Date approveTime;
    private Document document;
    private User approver;
}

设计要点:Document.processInstanceId 是业务表与 jBPM 表的唯一纽带;反过来,流程实例通过流程变量 document 保存公文 ID,实现双向可查。


四、流程定义管理

4.1 部署流程定义

public void deployProcessDefinition(byte[] processDefinition, byte[] processImage) {
    // 1. 解析 XML 得到流程定义对象
    ProcessDefinition def = ProcessDefinition.parseXmlInputStream(
            new ByteArrayInputStream(processDefinition));

    // 2. 部署到 jBPM(会自动升版本)
    getContext().deployProcessDefinition(def);

    // 3. 在 OA 侧保存一份(供展示流程图片、按名称查询)
    Workflow workflow = (Workflow) getSession()
            .createQuery("select w from Workflow w where w.name = ? ")
            .setParameter(0, def.getName())
            .uniqueResult();

    if (workflow == null) {
        workflow = new Workflow();
        workflow.setName(def.getName());
        workflow.setProcessDefinition(processDefinition);
        workflow.setProcessImage(processImage);
        getHibernateTemplate().save(workflow);
        return;
    }
    workflow.setName(def.getName());
    workflow.setProcessDefinition(processDefinition);
    workflow.setProcessImage(processImage);
    getHibernateTemplate().update(workflow);
}

页面上提供上传表单,同时上传 processdefinition.xml 和 processimage.jpg。

4.2 删除流程定义

jBPM 对流程定义做版本管理,删除时要删掉所有版本:

public void delWorkflow(int workflowId) {
    Workflow workflow = (Workflow) getHibernateTemplate().load(Workflow.class, workflowId);
    getHibernateTemplate().delete(workflow);

    List defs = getContext().getGraphSession()
            .findAllProcessDefinitionVersions(workflow.getName());
    for (Iterator iter = defs.iterator(); iter.hasNext();) {
        ProcessDefinition def = (ProcessDefinition) iter.next();
        getContext().getGraphSession().deleteProcessDefinition(def);
    }
}

五、公文的完整生命周期

5.1 新建公文并启动流程

public void addDocument(Document document, int workflowId, int userId) {
    document.setWorkflow((Workflow) getHibernateTemplate().load(Workflow.class, workflowId));
    document.setCreator((User) getHibernateTemplate().load(User.class, userId));
    document.setStatus(Document.STATUS_NEW);
    document.setCreateTime(new Date());
    getHibernateTemplate().save(document);

    // 创建流程实例,并把公文 ID 作为流程变量绑定
    long processInstanceId = workflowManager.addProcessInstance(
            document.getWorkflow().getName(), document.getId());

    document.setProcessInstanceId(processInstanceId);
    getHibernateTemplate().update(document);
}
public long addProcessInstance(String workflowName, int documentId) {
    JbpmContext context = getContext();
    ProcessDefinition definition = context.getGraphSession()
            .findLatestProcessDefinition(workflowName);

    ProcessInstance instance = new ProcessInstance(definition);
    instance.getContextInstance().createVariable("document", documentId);  // 关键绑定
    context.save(instance);

    return instance.getId();
}

5.2 查询待我审批的公文

public List searchApprovingDocuments(String username) {
    JbpmContext context = getContext();
    List docIds = new ArrayList();

    List tasks = context.getTaskMgmtSession().findTaskInstances(username);
    for (Iterator iter = tasks.iterator(); iter.hasNext();) {
        TaskInstance taskInstance = (TaskInstance) iter.next();

        // 只保留"正在等待审批"的任务
        if (!taskInstance.isSignalling()) continue;

        Integer docId = (Integer) taskInstance.getProcessInstance()
                .getContextInstance().getVariable("document");
        docIds.add(docId);
    }
    return docIds;
}

isSignalling() 用于过滤掉那些已经处理过、或处于会签中尚未轮到的任务。

5.3 查询下一步有哪些流向

页面要给出"提交给谁"的下拉框。注意起始节点没有任务实例,必须特殊处理:

public List searchNextTransitions(String username, long processInstanceId) {
    JbpmContext context = getContext();
    ProcessInstance instance = context.getProcessInstance(processInstanceId);

    String currentNodeName = instance.getRootToken().getNode().getName();
    String startNodeName   = instance.getProcessDefinition().getStartState().getName();

    Collection nextSteps = null;
    if (currentNodeName.equals(startNodeName)) {
        // 起始节点:直接从 Token 取可用流向
        nextSteps = instance.getRootToken().getAvailableTransitions();
    } else {
        // 普通节点:先找到该用户对应的任务实例,再取它的可用流向
        List tasks = context.getTaskMgmtSession().findTaskInstances(username);
        for (Iterator iter = tasks.iterator(); iter.hasNext();) {
            TaskInstance taskInstance = (TaskInstance) iter.next();
            if (taskInstance.getProcessInstance().getId() == processInstanceId) {
                nextSteps = taskInstance.getAvailableTransitions();
                break;
            }
        }
    }

    List transitions = new ArrayList();
    for (Iterator iter = nextSteps.iterator(); iter.hasNext();) {
        transitions.add(((Transition) iter.next()).getName());
    }
    return transitions;
}

这个 username 参数是后来补上的(原先只传 processInstanceId)。原因很实际:同一个人可能在多个流程实例中有任务,只靠流程实例 ID 无法唯一定位到"当前这个人对这份公文的任务"。

5.4 驱动流程前进

public String flowToNextStep(String username, long processInstanceId, String transitionName) {
    JbpmContext context = getContext();
    ProcessInstance instance = context.getProcessInstance(processInstanceId);

    String currentNodeName = instance.getRootToken().getNode().getName();
    String startNodeName   = instance.getProcessDefinition().getStartState().getName();

    if (currentNodeName.equals(startNodeName)) {
        // 起始节点没有任务实例,用 signal 触发
        instance.getRootToken().signal(transitionName);
    } else {
        // 普通节点:结束当前任务实例,从而触发流转
        List tasks = context.getTaskMgmtSession().findTaskInstances(username);
        for (Iterator iter = tasks.iterator(); iter.hasNext();) {
            TaskInstance taskInstance = (TaskInstance) iter.next();
            if (taskInstance.getProcessInstance().getId() == processInstanceId) {
                taskInstance.end(transitionName);
                break;
            }
        }
    }

    String status = instance.getRootToken().getNode().getName();
    if (instance.hasEnded()) {
        status = Document.STATUS_END;   // "完成"
    }
    return status;
}

业务层包装:

public void submitToWorkflow(int userId, int documentId, String transitionName) {
    User user = (User) getHibernateTemplate().load(User.class, userId);
    Document document = (Document) getHibernateTemplate().load(Document.class, documentId);

    String status = workflowManager.flowToNextStep(
            user.getUsername(), document.getProcessInstanceId(), transitionName);

    document.setStatus(status);            // 把节点名当作公文状态显示
    getHibernateTemplate().update(document);
}

状态设计很巧妙:直接用 jBPM 的节点名作为公文状态(如"部门经理审批"、"总经理审批"),不额外维护状态机;流程结束则置为"完成"。

5.5 审批

public void addApproveInfo(ApproveInfo approveInfo, int documentId, int approverId) {
    approveInfo.setDocument((Document) getHibernateTemplate().load(Document.class, documentId));
    approveInfo.setApprover((User) getHibernateTemplate().load(User.class, approverId));
    getHibernateTemplate().save(approveInfo);
}

审批意见与流程流转是两个独立动作:先写审批意见,再选择流向提交。这也符合实际办公习惯(批注 + 转交)。

5.6 删除公文

public void delDocument(int documentId) {
    Document document = (Document) getHibernateTemplate().load(Document.class, documentId);
    getHibernateTemplate().delete(document);
    workflowManager.delProcessInstance(document.getProcessInstanceId());   // 同步删除流程实例
}

六、流程定义示例:报销单

<process-definition name="报销单">
   <start-state name="start">
      <transition name="提交赵一" to="赵一"/>
   </start-state>

   <task-node name="赵一">
      <event type="node-enter">
         <action class="com.oa.managers.CopyPropertiesActionHandler"/>
      </event>
      <task><assignment actor-id="zy"/></task>
      <transition name="提交孙三" to="孙三" condition="#{money le 10000}"/>
      <transition name="提交李四" to="李四" condition="#{money le 10000}"/>
      <transition name="提交钱二" to="钱二" condition="#{money gt 10000}"/>
      <transition name="提交周五" to="周五" condition="#{money gt 10000}"/>
   </task-node>

   <task-node name="钱二">
      <task><assignment actor-id="qe"/></task>
      <transition name="提交领导三人会签" to="领导三人会签" condition="#{money gt 100000}"/>
      <transition name="小于10万,直接提交陈十" to="陈十" condition="#{money le 100000}"/>
   </task-node>

   <!-- 会签:三个领导并行审批,全部完成后汇聚 -->
   <fork name="领导三人会签">
      <transition name="提交郑七" to="郑七"/>
      <transition name="提交王八" to="王八"/>
      <transition name="提交冯九" to="冯九"/>
   </fork>
   <join name="join1">
      <transition to="陈十"/>
   </join>

   <!-- 三选一审批:任一人通过即可 -->
   <task-node name="三巨头审批" signal="first">
      <task name="t1"><assignment actor-id="zyy"/></task>
      <task name="t2"><assignment actor-id="wye"/></task>
      <task name="t3"><assignment actor-id="jys"/></task>
      <transition name="提交沈一四" to="沈一四"/>
   </task-node>

   <end-state name="end1"/>
</process-definition>

这个示例几乎涵盖了全部流程模式:

模式 XML 元素 说明
条件分支 condition="#{money gt 10000}" 按金额走不同审批路径
并行会签 <fork> + <join> 三人都要审完才继续
或签 <task-node signal="first"> 任一人完成即继续
固定指派 <assignment actor-id="zy"/> 任务分配给指定账号
节点事件 <event type="node-enter"><action class="..."/></event> 进入节点时执行一段 Java 代码

七、动态表单变量如何参与流程判断

条件表达式 #{money gt 10000} 里的 money 是动态表单里用户填写的字段,它本来存在 Document.props 这个 Map 里,jBPM 看不见。解决办法是一个 ActionHandler,在进入节点时把它拷进流程变量:

public class CopyPropertiesActionHandler implements ActionHandler {
    public void execute(ExecutionContext executionContext) throws Exception {
        Session session = executionContext.getJbpmContext().getSession();

        int documentId = (Integer) executionContext.getContextInstance().getVariable("document");
        Map props = ((Document) session.load(Document.class, documentId)).getProps();

        Map target = new HashMap();
        for (Iterator iter = props.entrySet().iterator(); iter.hasNext();) {
            Map.Entry entry = (Map.Entry) iter.next();
            DocumentProperty prop = (DocumentProperty) entry.getValue();

            // 按非空原则挑出实际填写的值
            if (prop.getJava_io_File() != null)    target.put(entry.getKey(), prop.getJava_io_File());
            if (prop.getJava_lang_Integer() != null) target.put(entry.getKey(), prop.getJava_lang_Integer());
            if (prop.getJava_lang_String() != null)  target.put(entry.getKey(), prop.getJava_lang_String());
        }

        executionContext.getContextInstance().addVariables(target);
    }
}

在流程定义里挂载:

<task-node name="赵一">
   <event type="node-enter">
      <action class="com.oa.managers.CopyPropertiesActionHandler"/>
   </event>
   ...
</task-node>

效果:用户在表单里填了 money=50000,进入"赵一"节点时该值被拷进流程变量,于是 #{money gt 10000} 就能正确求值,流程自动走"钱二"分支。

这就是"动态表单 + 工作流"的粘合剂:表单定义字段,Handler 把值注入流程,流程用表达式做路由。


八、jBPM 九步入门练习

配套示例工程按操作顺序提供了 9 个类,建议照着跑一遍:

序号 类 操作
01 Jbpm_01_CreateTable 创建 jBPM 系统表
02 Jbpm_02_DeployProcessDefinition 部署流程定义
03 Jbpm_03_CreateDocument 创建业务数据(公文)
04 Jbpm_04_CreateProcessInstance 创建流程实例并绑定业务 ID
05 Jbpm_05_SubmitDocument 提交公文,流程前进
06 Jbpm_06_CurrentNode 查询当前所处节点
07 Jbpm_07_SearchMyTaskList 查询我的待办任务列表
08 Jbpm_08_NextNode 查询下一步可选流向
09 Jbpm_09_ProcessInstanceIsEnded 判断流程是否结束

九、关键设计回顾

  1. 双向绑定:公文表存 processInstanceId,流程实例存变量 document,两边都能反查。
  2. 状态即节点:直接用 jBPM 节点名作为公文状态,省掉一套独立状态机。
  3. 共享 Session:context.setSession(getSession()) 保证业务与流程在同一事务内,这是数据一致性的前提。
  4. 起始节点特殊处理:起始节点没有 TaskInstance,必须用 token.signal() 而非 taskInstance.end()。
  5. 流程变量驱动路由:CopyPropertiesActionHandler 把表单值注入流程变量,让条件分支可以基于业务数据。

要点小结

  • | 概念 | 对应类 | 含义 | |---|---|---| | 流程定义 | ProcessDefinition | 一张流程图(XML),可有多个版本 | | 流程…
  • 这就是"动态表单 + 工作流"的粘合剂:表单定义字段,Handler 把值注入流程,流程用表达式做路由。

由站内小编编辑整理

Related