用户手册指引模板.doc

jBPM 用户手册

目 录

jBPM 用户手册 - 1 -
第一章 概述 - 3 -
第二章 安装 - 8 -
第三章 步骤 - 10 -
第四章 BPMN2.0 - 21 -
第五章 API - 22 -
第六章 人工任务 - 23 -
第七章 领域 - 规范步骤 - 33 -
第八章 持久化 - 34 -
第九章 控制台 - 39 -
第十章 监视 - 42 -

第一章　 概述
本章节将介绍jBPM5多种组件。组件将带您快速了解业务步骤生命周期和阶段。这些阶段包含建模、布署、实施和监视。

1. 建模
jBPM 许可用户经过图形方法修改业务步骤。用户和开发者可经过三种方法修改BPMN2.0业务步骤定义。
1.1. Drools Flow for eclipse插件
Drools Flow支持创建，调试步骤。
1.2. jBPM5 for eclipse 插件
现在仍在开发中，仅支持创建步骤。完成后版本将完全支持BPMN2.0规范。
1.3. 基于WEBOryx编辑器(EXT 实现)
Oryx编辑器整合到Guvnor，它是一个存放步骤知识库。Oryx编辑器支持查看、更新和创建步骤。

2. 布署
Guvnor 是一个知识库，用来存放步骤、域模型、业务规则等。它提供一个基于WEB控制台用来查找、修改和测试你知识库内容。

3. 实施
3.1. 步骤引擎
步骤引擎是一个基于JAVA语言开发轻量级工作流引擎。
v 内置支持BPMN 2.0规范步骤
v 插件化数据持久层和事务配置
v 审计和历史日志统计
v 基于通用步骤引擎
现在步骤引擎还没有实现BPMN 2.0全部结点类型和属性，但大部分通用结点类型已支持。
下图列出全部jBPM5已支持元素：

下面列出全部BPMN 2.0 定义元素：
步骤对象
事件
* Start Event (None, Conditional, Signal, Message, Timer)
* End Event (None, Terminate, Error, Escalation, Signal, Message, Compensation)
* Intermediate Catch Event (Signal, Timer, Conditional, Message) 立即捕捉事件
* Intermediate Throw Event (None, Signal, Escalation, Message, Compensation)
* Non-interrupting Boundary Event (Escalation, Timer) 非中止边界事件
* Interrupting Boundary Event (Escalation, Error, Timer, Compensation)
活动
* Script Task (Java 、 MVEL) JAVA或MVEL脚本表示式语言
* Task
* Service Task
* User Task
* Business Rule Task
* Manual Task
* Send Task
* Receive Task
* Reusable Sub-Process (Call Activity) 可复用子步骤
* Embedded Sub-Process 嵌入子步骤
* Ad-Hoc Sub-Process 点对点子步骤
* Data-Object
关口
* 分支
* Exclusive (Java, MVEL or XPath expression language) 排斥
* Inclusive (Java, MVEL or XPath expression language) 包含
* Parallel 并行
* Event-Based
* 合并
* Exclusive 排斥
* Parallel 并行
* Lanes
数据
* Java type language
* Process properties
* Embedded Sub-Process properties
* 活动properties
连接对象
* Sequence flow 时序流

3.2. 人工任务服务 WS-HT
人工任务服务是BPM业务步骤管理处理方案一个关键组成部分。 一些任务能够自动实施而不需要和人交互，但有些任务需要和人交互。jBPM5中 actors代表人抽象，也就是说不一定是人，能够是阿猫阿狗。jBPM5默认提供了一个和actors交互实现，WS－HT。WS－HT也支持组设置，升级，分配规则等。

3.3. 监视
步骤监听器Process listeners可监听步骤引擎运行时环境发生多种事件，如步骤实例开启、结点实例完成等。这些信息可用来创建历史日志进行报表静态分析或供BAM业务活动监控进行动态分析。
3.3.1. 基于WEB步骤管理控制台
.localhost:8080/jbpm-console
用户名/密码：krisv/krisv

经过此控制台能够管理步骤实例。进入步骤Overview能够开启步骤，查看步骤，停止步骤。进入个人任务能够进行步骤操作。进入报表能够查看步骤报表。

第二章　 安装
参考

Guvnor使用：
.localhost:8080/drools-guvnor
使用视频：

若有安装问题，可这么子：
Email:
IRC: #jbpm at irc.codehaus.org
jBPM用户论坛
.community.jboss.org/en/jbpm?view=discussions
FAQ：
1. 脚本不能下载组件？
检验网络，或直接手动下载后放到 jbpm-installer/lib 文件夹。
2. 下载组件不能解压？
文件有问题，重新下载。
3. 清除安装？
ant clean.demo
4. 重新开启报异常？
手感人工服务结束进程，再重新开启。这是脚本缺点造成。
5. 控制台或Guvroy 报错？
检验${jboss.home}/server/default/log。如不能处理，发到论坛。

第三章　 步骤

v 业务步骤是一张步骤图表，描述一系列实施步骤次序。它由多个结点组成，结点之间相互连接。
v 结点代表总步骤一个步骤，
v 箭头代表结点之间连接，它指定怎样从一个结点流向另外一个结点。
v BMPN2.0 已经预定义了一组结点元素。
本章节介绍怎样定义和使用结点。

1. 创建步骤
创建步骤有三种方法：
v Eclipse BPMN2.0图形编辑器插件
v 文本编辑器
v 直接创建经过步骤API
步骤文件扩展名：bpmn　bpmn2。
图形编辑器插件需要打开属性面板配置元素属性。
XML形式：
<?xml version="1.0" encoding="UTF-8"?>
expressionLanguage="...mvel.org/2.0"
xmlns="...omg.org/spec/BPMN/0524/MODEL"Rule Task
xmlns:xsi="...w3.org//XMLSchema-instance"
xsi:schemaLocation="...omg.org/spec/BPMN/0524/MODEL BPMN2
xmlns:g="...jboss.org/drools/flow/gpd"
xmlns:bpmndi="...omg.org/spec/BPMN/0524/DI"
xmlns:dc="...omg.org/spec/DD/0524/DC"
xmlns:di="...omg.org/spec/DD/0524/DI"
xmlns:tns="...jboss.org/drools">
<process processType="Private" isExecutable="true" id="com.sample.hello" name=
Process" >
<!-- nodes -->
<startEvent id="_1" name="Start" />
<scriptTask id="_2" name="Hello" >
<script>System.out.println("Hello World");</script>
</scriptTask>
<endEvent id="_3" name="End" >
<terminateEventDefinition/>
</endEvent>
<!-- connections -->
<sequenceFlow id="_1-_2" sourceRef="_1" targetRef="_2" />
<sequenceFlow id="_2-_3" sourceRef="_2" targetRef="_3" />
</process>
<bpmndi:BPMNDiagram>
<bpmndi:BPMNPlane bpmnElement="com.sample.hello" >
<bpmndi:BPMNShape bpmnElement="_1" >
<dc:Bounds x="16" y="16" width="48" height="48" />
</bpmndi:BPMNShape>
<bpmndi:BPMNShape bpmnElement="_2" >
<dc:Bounds x="96" y="16" width="80" height="48" />
</bpmndi:BPMNShape>
<bpmndi:BPMNShape bpmnElement="_3" >
<dc:Bounds x="208" y="16" width="48" height="48" />
</bpmndi:BPMNShape>
<bpmndi:BPMNEdge bpmnElement="_1-_2" >
<di:waypoint x="40" y="40" />
<di:waypoint x="136" y="40" />
</bpmndi:BPMNEdge>
<bpmndi:BPMNEdge bpmnElement="_2-_3" >
<di:waypoint x="136" y="40" />
<di:waypoint x="232" y="40" />
</bpmndi:BPMNEdge>
</bpmndi:BPMNPlane>
</bpmndi:BPMNDiagram>
</definitions>

API 方法：
为了屏蔽内部API，不推荐使用。
关键步骤已经定义在org.jbpm.workflow.core 和org.jbpm.workflow.core.node包中。你能够经过工厂来创建步骤。示例在 源码包junit tests中。

package org.jbpm.process;

import org.jbpm.JbpmTestCase;
import org.jbpm.ruleflow.core.RuleFlowProcessFactory;

public class ProcessFactoryTest extends JbpmTestCase {

public void testProcessFactory() {
RuleFlowProcessFactory factory = RuleFlowProcessFactory.createProcess("org.drools.process");
factory
// header
.name("My process").packageName("org.drools")
// nodes
.startNode(1).name("Start").done()
.actionNode(2).name("Action")
.action("java", "System.out.println(\"Action\");").done()
.endNode(3).name("End").done()
// connections
.connection(1, 2)
.connection(2, 3);
factory.validate().getProcess();
}

}

更多代码：

2. 使用步骤
2.1. 创建知识库
KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();
kbuilder.add( ResourceFactory.newClassPathResource("MyProcess.bpmn2"),
ResourceType.BPMN2 );
KnowledgeBase kbase = kbuilder.newKnowledgeBase();
2.2. 创建会话开启步骤
步骤开启需要显式调用 startProcess 方法。
StatefulKnowledgeSession ksession = kbase.newStatefulKnowledgeSession();
ksession.startProcess("com.sample.hello");
参数 com.sample.hello 代表步骤ID。
startProcess(String processId, Map parameters) 方法Map参数可传入额外参数，这些参数是键值对。注意这些参数将被复制到步骤实例，作为步骤顶级变量。顶级变量是指变量作用或是顶级。

2.3. 结点类型细节解释
步骤有以下属性：
ID： 惟一
NAME： 显示名称
VERSION：　版本
Package：　命名空间
Variables：　变量，用于传输数据
Swimlanes：　泳道（专用通道），指定实施人工任务actor
Connection Layout连接布局
Manual　：　人工
Shortest path　：　最短路径
Manhattan　：　曼哈顿

BMPN 支持结点类型以下：

开始事件和结束事件， 一个步骤必需有一个开始事件，一个或多个结束事件。结束事件Terminate假如为ＴＲＵＥ，那么将结束整个步骤，不然若有多个结束事件只会结束对应结束事件路径。如T2-E2.
| - T1 - E1(Terminate=false)
S - +
| - T2 - E2(Terminate=false)

Rule Task 代表需要实施一组规则集。规则定义在多个分离文件中，格式要求为Drools rule format。规则能够成为标准规则流组一部分经过在头部使用ruleflow-group属性。
ruleflow-group实施可认为是一个队列。新来必需等前面实施完才会实施。

Diverging Gateway　分支结点，一进多出。Gateway 不好翻译，所以省略。
AND parallel 和，并行，　两个全部要满足（同时）
XOR or exclusive　异或，排斥，只选择其中一个
OR or inclusive 或，包含，最少只要有一个满足即可(不一样时)

Converging Gateway 合并结点，多进一出。
AND parallel 和，并行，　两个全部要满足（同时）
XOR or exclusive　异或，排斥，只选择其中一个

Reusable Sub-Process　可复用子步骤
Wait for completion 等候完成
On-entry and on-exit actions：绑定入口和出品action.
Parameter in/out mapping: in表示输入参数 out 表示输入参数和返回，只有当Wait for completion为true时,out 才能够使用。

Script Task 代表一个可实施脚本。支持Java ， MVEL 方言。脚本绑定到Action.
Action: 绑定Action.

Timer Event 定时器事件
Timer delay 延迟时间ms

Error Event 异常事件
FaultName 异常处理器名
FaultVariable 异常变量

.Message Event 消息事件, 没有输入
EventType 监听事件类型
VariableName 事件数据
Scope
internal 步骤内部事件 external 外部事件
.User Task 用户任务（人工任务）
ActorId 责任人，多个人用逗号“，”分隔
GroupId 组，多个组用逗号“，”分隔
Skippable 表示这个任务是否可忽略，即不实施就结束。
Swimlane 泳道
On.entry /on-exit actions: 绑定入口、出口Action
Parameter mapping 传入参数
Result mapping 返回结果
Content: 任务数据

.Sub-Process 子步骤

.Multiple Instances 多实例子步骤，特殊子步骤，许可实施数次

Service Task（Work Item node）代表一个抽象任务。可经过它扩展任务。
Additional parameters 扩展参数定义
Data
变量，顶级、子级，继承树
约束：包含代码约束和规则约束

Actions
Action 能够访问全局，步骤变量，知识库上下文预定义变量，访问运行时，开启步骤，分发事件，插入数据。

Events
事件类型 － 事件监听（消息事件） － 事件处理（action）
事件分发：
内部事件 步骤管理
外部事件 action
Timers
定时器

更新步骤
// create the session and start the process "com.sample.process"
KnowledgeBuilder kbuilder = ...
StatefulKnowledgeSession ksession = ...
ProcessInstance processInstance = ksession.startProcess("com.sample.process");
// add a new version of the process "com.sample.process2"
kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();
kbuilder.add(..., ResourceType.BPMN2);
kbase.addKnowledgePackages(kbuilder.getKnowledgePackages());
// migrate process instance to new version
Map<String, Long> mapping = new HashMap<String, Long>();
// top level node 2 is mapped to a new node with id 3
mapping.put("2", 3L);
// node 2, which is part of composite node 5, is mapped to a new node with id 4
mapping.put("5.2", 4L);
WorkflowProcessInstanceUpgrader.upgradeProcessInstance( ksession, processInstance.getId(), "com.sample.process2", mapping);

第四章　 BPMN2.0
现在jBPM5没有完全实现BPMN2.0规范。所以本章略过。

第五章　 API
本章是代码，前面已经贴过，不再多说。讲解了知识库、会话、步骤关系及怎样创建。

第六章　 人工任务

人工任务规范

jBPM5 使用UserTask结点表示人工任务（需要和actor交互任务）。UserTask 任务结点支持定义任务类型、actors和任务关联数据。经过 Task Service 可管理UserTask。
为了使用人工任务，你必需定义UserTask结点。一个UserTask 表示一个需要actor实施自动化任务。人工任务其实能够简单认为是任何类型外部服务。外部服务需要被调用，可看成特殊类型work item实现。
人工任务惟一特色是支持泳道来简化给用户分配任务。
UserTask 结点属性：
* Id: 结点惟一标识
* Name: 结点名称
* TaskName: 任务名称
* Priority: 优先级（整数）
* Comment: 任务注释
* ActorId: actor, 多个使用逗号","分隔
* Skippable: 任务可跳过（不实施就结束）
* Content: 任务关联数据
* Swimlane: 泳道，能够简化分配多个人工任务给同一个actor
* Wait for completion: 是否等候人工任务实施完成，若为False，则创建完人工任务后继续步骤。
* On-entry and on-exit actions: 绑定入口、出品事件处理器－action
* Parameter mapping: 参数
* Result mapping: 结果
* Timers: 定时器
* ParentId: 父人工服务ID

1. 泳道
说明：这个译法对于大家来讲，不明白怎么回事？但名词而已，纯靠前辈误导，慢慢误导就了解了。
使用泳道前必需在步骤定义属性中配置泳道集合。
多个人工任务使用同一泳道，第一个人工任务实施时，将会指定一个actorId. 后面人工任务即使显式指定actorId,，也不会起作用，而是使用第一个人工任务actorId。当然我们使用泳道就没必需再指定actorId，第一个除外。
试想，有这么一个场景，企业有2个部门，HR部和IT部；步骤定义了2个泳道HR、IT；步骤定义中包含4个人工任务，前两个人工任务需要和HR部经理交互，后两个人工任务需要和IT部经理交互。当我们指定前两个人工任务actorId 时，需要分配两次。后面两个也是如此。现在极端情况发生了，HR经理和HT经理调岗，我们是不是得去修改步骤定义下全部些人工服务actorId?而经过使用泳道，只需要修改第一个和第三个actorId。

泳道和actorId是一对多关系，也就是说，一个人工任务可指定给多个actor来处理。
泳道实质是什么，实质就是把人工任务进行分类，并绑定actor列表。

2. 人工任务管理组件
人工任务和其它外部服务类似，可作为work itme扩展被实现和调用。步骤仅包含人工任务实施所必需抽象描述。 work item handler是这个抽象描述标准实现。用户使用我们可拔插work item handler方法完成底层实现。
我们也提供了一个WS-HumanTask 规范管理组件。经过它来管理任务生命周期（创建，获取，完成，任务状态持久化）。同时也支持国际化、日历、多种分配类型，代理和生死线。

3. 人工任务生命周期

当一个步骤实例人工任务结点被触发，人工任务实例将被创建。当创建完成后，人工任务进入Created 状态。
当人工任务Wait for completion 属性为 False时，步骤会立即继续实施，不然要等候任务完成或终止。

进入Created 状态，任务将显示全部负责实施actors。等候她们来获取任务。一旦有一个actor 获取任务，任务进入 Reserved 状态。用户决定开始实施任务，此时任务进入 InProgress 状态。任务开始实施，实施完成后，用户必需完成任务。此时用户进入 Completed 状态。用户也能够决定任务已经失败，此时任务进入 Failed 状态。
上面介绍正常生命周期，其它包含：
Delegating /forwarding 任务, 分配任务给另外一个 actor 来处理
Revoking 回滚任务
Temporarly suspending and resuming 临时挂起或继续任务
Stopping a task in progress 停止正在实施任务
Skipping 跳过（不实施）

4. 链接人工任务管理组件和引擎
4.1. 注册 work item handler
work item handler功效是翻译抽象work item（如人工任务）为规范调用。
我们已经实现了个work item handler ，它在包jbpm-human-task中：
org.jbpm.process.workitem.wsht.WSHumanTaskHandler

注册代码示例：
StatefulKnowledgeSession ksession = ...;
ksession.getWorkItemManager().registerWorkItemHandler("Human
Task", new WSHumanTaskHandler());

若需要持久化会话内容，应该使用org.jbpm.process.workitem.wsht.CommandBasedWSHumanTaskHandler
它们全部默认使用Mina来提供C/S通信传输。
.mina.apache.org
愈加快速实现HornetQ 也是可行。
人工任务用户端使用以下生命周期管理方法：

5. 开启人工任务管理组件
前提：
数据表users ，groups 中数据已经配置好。你可能经过以下代码来添加用户和组：
taskSession.addUser(user)
taskSession.addGroup(group)
确保数据库相关表中最少有一个Administrator用户和 administrator 角色。我们提供evaluation评审示例中会自动加载两个用户和组配置文件：
jbpm-installer\task-service\resources\org\jbpm\
LoadUsers.mvel
LoadGroups.mvel

开启任务管理组件示例：
EntityManagerFactory emf = Persistence.createEntityManagerFactory("org.jbpm.task");
TaskService taskService = new TaskService(emf, SystemEventListenerFactory.getSystemEventListener());
MinaTaskServer server = new MinaTaskServer( taskService );
Thread thread = new Thread( server );
thread.start();

任务管理组件使用JPA来存放任务数据，所以需要配置persistence.xml
下面是任务管理组件使用 Hibernate 和 H2 数据库存示例：
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<persistence
version="1.0"
xsi:schemaLocation=
"

xmlns:orm="
xmlns:xsi="...w3.org//XMLSchema-instance"
xmlns="
<persistence-unit name="org.drools.task">
<provider>org.hibernate.ejb.HibernatePersistence</provider>
<class>org.jbpm.task.Attachment</class>
<class>org.jbpm.task.Content</class>
<class>org.jbpm.task.BooleanExpression</class>
<class>org.jbpm.task.Comment</class>
<class>org.jbpm.task.Deadline</class>
<class>org.jbpm.task.Comment</class>
<class>org.jbpm.task.Deadline</class>
<class>org.jbpm.task.Delegation</class>
<class>org.jbpm.task.Escalation</class>
<class>org.jbpm.task.Group</class>
<class>org.jbpm.task.I18NText</class>
<class>org.jbpm.task.Notification</class>
<class>org.jbpm.task.EmailNotification</class>
<class>org.jbpm.task.EmailNotificationHeader</class>
<class>org.jbpm.task.PeopleAssignments</class>
<class>org.jbpm.task.Reassignment</class>
<class>org.jbpm.task.Status</class>
<class>org.jbpm.task.Task</class>
<class>org.jbpm.task.TaskData</class>
<class>org.jbpm.task.SubTasksStrategy</class>
<class>org.jbpm.task.OnParentAbortAllSubTasksEndStrategy</class>
<class>org.jbpm.task.OnAllSubTasksEndParentEndStrategy</class>
<class>org.jbpm.task.User</class>
<properties>
<property name="hibernate.dialect" value="org.hibernate.dialect.H2Dialect"/>
<property name="hibernate.connection.driver_class" value="org.h2.Driver"/>
<property name="hibernate.connection.url" value="jdbc:h2:mem:mydb" />
<property name="hibernate.connection.username" value="sa"/>
<property name="hibernate.connection.password" value="sasa"/>
<property name="hibernate.connection.autocommit" value="false" />
<property name="hibernate.max_fetch_depth" value="3"/>
<property name="hibernate.hbm2ddl.auto" value="create" />
<property name="hibernat