公文流转与 jBPM 工作流
导读
关于「公文流转与 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 的表建起来
- 拷贝依赖 jar 到
WEB-INF/lib:jbpm-jpdl.jar、jbpm-identity.jar、bsh.jar、jcr-1.0.jar及 jboss 相关包; - 在
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>
- 类名冲突处理: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);
- 启动 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 |
判断流程是否结束 |
九、关键设计回顾
- 双向绑定:公文表存
processInstanceId,流程实例存变量document,两边都能反查。 - 状态即节点:直接用 jBPM 节点名作为公文状态,省掉一套独立状态机。
- 共享 Session:
context.setSession(getSession())保证业务与流程在同一事务内,这是数据一致性的前提。 - 起始节点特殊处理:起始节点没有 TaskInstance,必须用
token.signal()而非taskInstance.end()。 - 流程变量驱动路由:
CopyPropertiesActionHandler把表单值注入流程变量,让条件分支可以基于业务数据。
要点小结
- | 概念 | 对应类 | 含义 | |---|---|---| | 流程定义 |
ProcessDefinition| 一张流程图(XML),可有多个版本 | | 流程… -
-
- 这就是"动态表单 + 工作流"的粘合剂:表单定义字段,Handler 把值注入流程,流程用表达式做路由。
由站内小编编辑整理