Snaker用户手册.pdf

1、Snaker 用户 手册 目录 Snaker 用户手册 . 1 一、 常用操作 3 1、 流程定义部署 3 deploy . 3 redeploy . 3 undeploy. 3 2、 启动流程实例 4 根据 id 启动实例 . 4 根据 name 启动实例 . 4 3、 执行任务 4 4、 转派任务 5 5、 撤回任务 5 6、 提取任务 5 7、 任务驳回 5 8、 自由流程 6 9、 动态添加、减少参与者 7 10、 编码设置参与者 7 11、 节点拦截器 8 12、 参与者使用组 9 自定义访问策略 9 获取待办任务 9 执行任务 9 13、 委托代理 10 增加委托代理表 10 配置

2、拦截器 10 管理委托代理 10 14、 子流程 11 二、 应用整合 12 1、 API 方式整合 . 12 配置 snaker.xml . 12 编写帮助类 12 调用流程引擎 14 2、 与 Spring 整合 14 SnakerEngine 配置 . 14 DBAccess 配置 . 15 事务配置 16 三、 流程设计器 18 四、 API 说明 . 24 一、 常用操作 1、 流程 定义 部署 如何 使用流程设计器定义流程请参考 三 、流程设计器 。 部署 的 相关方法 包含： deploy、 redeploy、 undeploy， 分别表示 流程 定义 的部署、重新部署、卸载 。

3、 部署 时统一 使用 InputStream 输入流作为流程定义的数据。可借助org.snaker.engine.helper.StreamHelper帮助类 完成。 方法 如下定义： InputStream的方法 名称 描述 getStreamFromString 根据 字符串获取输入流 getStreamFromFile 根据 文件 对象 获取输入流 getStreamFromClasspath 根据类 路径 下的 资源文件 名称 获取输入流 getStreamFromUrl 根据 Url 远程 资源获取输入流 deploy engine.process().deploy(StreamHe

4、lper. getStreamFromClasspath(“test/task/simple/process.snaker“); 部署相同 的流程定义，会 产生 版本号依次加 1的 新的流程定义数据 。 但是 不会对 同名 的流程实例产生影响 。 redeploy engine.process().redeploy(processId, StreamHelper.getStreamFromClasspath(“test/task/simple/process.snaker“); 重新 部署流程会影响 当前 流程实例 的 执行 undeploy engine.process().undeploy

5、(processId); 卸载 流程只会更新状态 state值，不会 物理 删除数据。 2、 启动流程 实例 可根据流程定义的 id 或者 名称 启动 流程实例。如果 相同 的流程名称存在不同的版本 ，并 使用 名称启动实例 时 ，会按照最新的版本来启动 ， 其它 低版本 运行中的流程实例 不会 受到影响 ， 这样就 允许流程的多个版本同时运行。 根据 id 启动实例 engine.startInstanceById(processId); engine.startInstanceById(processId, “admin“); engine.startInstanceById(proces

6、sId, “admin“, args); 由 id启动实例的参数为： 流程 定义 id、操作人 operator、参数列表 args 根据 name 启动 实例 engine.startInstanceByName(“simple“); engine.startInstanceByName(“simple“, 0); engine.startInstanceByName(“simple“, 0, “admin“); engine.startInstanceByName(“simple“, 0, “admin“, args); 由 name启动实例的 参数 为：流程定义 name、 版本号 ve

7、rsion、 操作人 operator、参数列表 args 流程 实例的启动 会 在以下的表中产生数据： wf_order、 wf_hist_order 3、 执行 任务 执行 任务的处理逻辑包括两部分： 完成 当前任务 按照 流程定义产生新的任务 执行 任务的 api 如下： engine.executeTask(taskId); engine.executeTask(taskId, “admin“); engine.executeTask(taskId, “admin“, args); 执行 任务的 参数 为： 任务号 taskId、 操作人 operator、参数列表 args 4、 转

8、派 任务 任务 转派的业务逻辑是结束当前任务，并创建新的任务给 转派 人。其 调用 的 api 为： engine.task().createNewTask(task.getId(), 0, “test“); engine.task().complete(task.getId(); createNewTask方法 中的 第二个 参数 “ 任务类型 ”表示创建主办、协办任务。 5、 撤回 任务 根据历史 任务 id，撤回由该历史任务派发的所有 活动 任务 ， 如果无活动任务，则不允许撤回。 抛出 SnakerException异常 engine.task().withdrawTask(taskI

9、d, “admin“); 6、 提取 任务 任务提取一般 发生在参与者 为 部门 、 角色等组的情况下，该组的 某位 成员提取 任务 后， 其它成员无法处理任务。 engine.task().take(taskId, “admin“); 7、 任务 驳回 任务 驳回 有多种场景 ，常见的 有 ：驳回上一步、驳回到 任意 节点 engine.executeAndJumpTask(String taskId, String operator, Map args, String nodeName) 方法 的参数 nodeName决定 驳回的方式 ： nodeName为 空 （ null或空字符），则

10、驳回至 上一步 （不允许 驳回至 fork、 join、suprocess以及会签任务 ） nodeName非空，则根据 nodeName确定 跳转 的目标节点 。 该 实现原理 与其它流程引擎思路 一致 ，通过动态创建 连接 完成跳转。 8、 自由 流程 Snaker支持两种自由 流 ： 已经定义流转 节点， 由 用户 随意 在节点之间跳转 在 engine.executeAndJumpTask方法已经 支持 ， 参考 任务驳回 未 定义流转 节点 ，即流程定义没有流程模型的情况，由用户随意创建 自定义 任务 （任务名称、任务参与者、任务关联的表单等） TaskModel tm1 = new

11、 TaskModel(); tm1.setName(“task1“); tm1.setDisplayName(“任务 1“); List tasks = null; tasks = engine.createFreeTask(orderId, “1“, args, tm1); for(Task task : tasks) engine.task().complete(task.getId(), “1“, null); 自由 任务需要调用 engine.task().complete 方法结束 任务。 并且需要手动结束流程实例 。 engine.order().complete(order.ge

12、tId(); 自由 流程 存在强制终止的情况，此时需要调用 void terminate(String orderId); void terminate(String orderId, String operator); 强制 终止 实例先 结束该实例所有活动的任务，最后 结束 流程实例。 9、 动态 添加 、 减少参与者 添加 参与者需要判断所属的任务模型 的 参与类型 （ ANY、 ALL） ITaskService提供 两个添加参与者的方法 ： addTaskActor(String taskId, String. actors); 该方法根据 taskId对应的任务 模型判断是否 属于

13、会签任务 ， 如果属于 ALL的 参与类型，则添加的每个 actor 都会 产生 新的 任务。 如果 属于 ANY 的参与类型，则只是将actor添加到当前的任务中 addTaskActor(String taskId, Integer performType, String. actors); 该方法 根据 performType类型确定 是否 产生 新的任务 removeTaskActor(String taskId, String. actors); 减少 参与者仅仅是 将所属 任务的参与者删除 （参考 表 ： wf_task_actor） 10、 编码 设置参与者 编码 设置参与者 主

14、要 用到 AssignmentHandler 接口， 并在定义 任务 模型 时 ，需要 配置该接口的实现类： public class TaskAssign implements AssignmentHandler public Object assign(Execution execution) return “admin“; 此处 方便测试，直接返回字符串。实际 使用 时，应该根据执行对象的 args参数来判断执行人 。 11、 节点 拦截器 Snaker支持对 任意 类型的节点提供 前置 、后置拦截器处理。 preInterceptors 为 前置拦截器 属性 配置、 postInter

15、ceptors 为后置拦截器属性配置。 自定义 拦截器 需要实现 接口 ： SnakerInterceptor。 如下代码片段即实现对 产生的任务拦截并 输出 日志信息 : public class LocalTaskInterceptor implements SnakerInterceptor private static final Logger log = LoggerFactory.getLogger(LocalTaskInterceptor.class); public void intercept(Execution execution) if(log.isInfoEnabled

16、() log.info(“LocalTaskInterceptor start.“); for(Task task : execution.getTasks() StringBuffer buffer = new StringBuffer(100); buffer.append(“创建任务 标识 =“).append(task.getId(); buffer.append(“,名称 =“).append(task.getDisplayName(); buffer.append(“,创建时间 =“).append(task.getCreateTime(); buffer.append(“,参与者

17、 =“); if(task.getActorIds() != null) for(String actor : task.getActorIds() buffer.append(actor).append(“;“); buffer.append(“); log.info(buffer.toString(); log.info(“LocalTaskInterceptor finish.“); 12、 参与者 使用 组 自定义 访问 策略 public class CustomAccessStrategy extends GeneralAccessStrategy protected List e

18、nsureGroup(String operator) List groups = new ArrayList(); if(operator.equals(“test“) groups.add(“test“); else groups.add(“role1“); return groups; 继承 GeneralAccessStrategy类 ， 实现 ensureGroup方法，根据操作人获取该操作人对应的组 （ 部门、角色等） 在 snaker.xml中 增加访问策略类的配置： 获取 待办任务 获取 待办任务 时 ，设置的参与者数组增加组的信息即可 String actorIds = ne

19、w Stringusername, groups; snakerEngine.query().getWorkItems(page, new QueryFilter().setOperators(actorIds); 执行 任务 执行 任务的方式没有改变，依然是调用 snakerEngine.executeTask(taskId, userName, args); 13、 委托 代理 增加委托 代理 表 表 名称为 wf_surrogate， 其字段定义如下： 配置 拦截器 在 类路径下的 snaker.xml中 增加拦截器配置，如下： 由于 在 snaker.xml 中 配置的拦截器，属于全局

20、任务拦截器，则 当产生 新的任务时，会 执行 该拦截器负责检查委托代理表，是否存在委托授权情况，如存在，则增加代理人的参与权限 。 管理委托 代理 保存或 更新委托代理配置 engine.manager().saveOrUpdate(Surrogate surrogate); 删除委托 代理配置 engine.manager().deleteSurrogate(String id); 根据 id获取委托代理对象 engine.manager().getSurrogate(String id); 根据当前 操作人 、 流程名称获取该操作人的代理人，支持 多级 代理 engine.manager(

21、).getSurrogate(String operator, String processName) 14、 子流程 子流程 定义，主要是设置 processName（ 子流程的 名称 name 值 ）属性 二、 应用 整合 1、 API 方式 整合 API 整合 方式适用于 无业务容器托管 的 场景 。 配置 snaker.xml 参数类型 访问对象 事务管理拦截器 DataSource JdbcAccess DataSourceTransactionInterceptor SessionFactory HibernateAccess Hibernate3TransactionInterc

22、eptor SqlSessionFactory MybatisAccess MybatisTransactionInterceptor 编写 帮助类 import javax.sql.DataSource; import org.snaker.engine.SnakerEngine; import org.snaker.engine.access.jdbc.JdbcHelper; import org.snaker.engine.cfg.Configuration; /* * Snaker引擎帮助类 */ public class SnakerHelper private static fin

23、al SnakerEngine engine; static DataSource dataSource = JdbcHelper.getDataSource(); engine = new Configuration() .initAccessDBObject(dataSource) .buildSnakerEngine(); public static SnakerEngine getEngine() return engine; 考虑 到 与现有应用整合， 故提供 initAccessDBObject方法 ，由 应用 系统提供具体的 数据库访问对象，目前支持（ jdbc方式 DataSo

24、urce、 hibernate方式 SessionFactory、 mybatis方式 SqlSessionFactory） 。测试 用例 的 基类中 没有 调用 该方法。代码 如下 ： 类 路径： org.snaker.engine.test.TestSnakerBase public class TestSnakerBase protected String processId; protected SnakerEngine engine = getEngine(); protected IProcessService processService = engine.process();

25、protected IQueryService queryService = engine.query(); private SnakerEngine getEngine() return new Configuration().buildSnakerEngine(); 为了 方便测试， Snaker根据所使用的 DBAccess实现类，从 snaker.properties中 获取初始化参数，如下： jdbc.driver=com.mysql.jdbc.Driver jdbc.url=jdbc:mysql:/localhost:3306/snaker jdbc.username=root j

26、dbc.password=root 调用 流程引擎 SnakerHelper.getEngine().process().deploy(); 2、 与 Spring 整合 Spring 集成 Snaker 时，需要配置流程引擎、事务管理、数据访问方式 .具体可参考 snaker-demo。 具体 配置 如下： SnakerEngine 配置 DBAccess 配置 Hibernate 方式 使用 hibernate时，需要 在 sessionFactory配置中增加 snaker映射文件 的 mappingResources属性 ： hbm/snaker.task.hbm.xml hbm/sn

27、aker.order.hbm.xml hbm/snaker.ccorder.hbm.xml hbm/snaker.process.hbm.xml hbm/snaker.taskactor.hbm.xml hbm/snaker.workitem.hbm.xml hbm/snaker.surrogate.hbm.xml SpringJdbc 方式 Mybatis 方式 使用 mybatis，需要在 mybatis.cfg.xml配置 文件中增加 snaker的类型 及 映射文件 事务 配置 基于 Spring 的项目在使用 Snaker 时，完全将事务交给 Spring 托管 ，其 事务配置如下：

28、 三、 流程 设计器 1. 安装 插件 获取插件位置 : snaker-core-master/dist/plugins/snaker-designer_*.*.*.jar 安装插件 : 复制 snaker-designer_*.*.*.jar到 eclipse的 plugins目录下，重新启动eclipse即可 (经过测试的版本有 eclipse4.2/4.3) 2. 定义流程 依次选择 File-New-Other-Snaker，如果安装成功，如下图所示 : 选择 Snaker Process File并输入文件名称，如下图所示 : 点击 Finish，则打开流程设计器主界面，其中包括两大

29、部分 :流程组件、属性Properties视图，如下图所示 : 3. 流程组件 : 目前节点组件包括 :start、 end、 task、 custom、 sub-process、 decision、fork、 join，分别对应开始、结束、任务、自定义、子流程、决策、分支、合并组件模型 . 4. 属性视图 : 对组件模型设置属性，包括常用的 name、 displayName等 5. 布局工具 : 右上角的网格、几何对齐用于图形布局 . 6. 属性说明 组件模型 属性 描述 通用属性 name 组件名称，模型内名称唯一 displayName 组件中文显示名称，方便阅读 preInterce

30、ptors 前置拦截器 (节点 模型 ) postInterceptors 后置拦截器 (节点 模型 ) Process instanceUrl 流程定义列表页面直接启动流程实例的 URL instanceNoClass 流程实例编号生成类 Transition expr 决策选择 Decision 节点的输出变迁表达式 Task form 用户参与的表单任务对应的 URL assignee 任务参与者变量 assignmentHandler 任务参与者处理类 taskType 任务类型 （ Main： 主办； Aidant：协办） performType 任务参与类型（针对多个参与者） AN

31、Y 为其中一个参与者完成即往下流转； ALL 为所有参与者完成才往下流转 expireTime 期望完成时间，设置表达式变量由参数传递 autoExecute 是否 自动执行： Y 自动； N 非自动 callback 执行 后的回调类 reminderTime 提醒 时间 reminderRepeat 提醒 次数 Custom clazz 自定义节点的 Java 类路径，两种方式： 1.实现 IHandler 接口 2.无接口实现的普通 java 类，需要设置下面方法名称、参数属性 methodName 定义需要执行的 java 类的方法名称 args 定义传递的参数表达式 var 定义返回

32、值变量名称 SubProcess processName 子流程名称（对应 process 的 name 属性） Decision expr 决策选择表达式 handleClass 决策选择的处理类，实现 DecisionHandler 接口 7. 自定义 模型 Snaker流程设计器中的组件 模型是 通过 xml 的 配置加载 的 。 配置 文件请参考： http:/ 如 Decision节点的配置 如下 ： 配置 内容包括属性、显示图标、节点名称 等。 如果 需要增加节点模型， 只需要 参考 component的属性定义即可。 model-process.xml文件 注释了 Sql节点的定

33、义， 仅供 参考 。 自定义 配置完成后， 需要更新 配置文件，步骤如下： 选择 Window-Preferences打开 首选项 选择 配置面板： 在 配置面板中，点击按钮 “Browse”选择 自定义模型配置的 XML文件即可 。 四、 API 说明 1. SnakerEngine: /获取 process服务 IProcessService process(); /获取查询服务 IQueryService query(); /获取实例服务 IOrderService order(); /获取任务服务 ITaskService task(); /获取管理服务 IManagerService

34、 manager(); /根据流程定义 ID启动流程实例 Order startInstanceById(String id); /根据流程定义 ID，操作人 ID启动流程实例 Order startInstanceById(String id, String operator); /根据流程定义 ID，操作人 ID，参数列表启动流程实例 Order startInstanceById(String id, String operator, Map args); /根据流程名称启动流程实例 Order startInstanceByName(String name); /根据流程名称、版本号启

35、动流程实例 Order startInstanceByName(String name, Integer version); /根据流程名称、版本号、操作人启动流程实例 Order startInstanceByName(String name, Integer version, String operator); /根据流程名称、版本号、操作人、参 数列表启动流程实例 Order startInstanceByName(String name, Integer version, String operator, Map args); /根据父执行对象启动子流程实例 Order startIn

36、stanceByExecution(Execution execution); /根据任务主键 ID执行任务 List executeTask(String taskId); /根据任务主键 ID，操作人 ID执行任务 List executeTask(String taskId, String operator); /根据任务主键 ID，操作人 ID，参数列表执行任务 List executeTask(String taskId, String operator, Map args); /根据任务主键 ID，操作人 ID，参数列表执行任务，并且根据 nodeName跳转到任意节点 List

37、executeAndJumpTask(String taskId, String operator, Map args, String nodeName); /根据流程实例 ID，操作人 ID，参数列表按照节点模型 model创建新的自由任务 List createFreeTask(String orderId, String operator, Map args, WorkModel model); 2. IProcessService: /保存流程定义 void saveProcess(Process process); /根据主键 ID获取流程定义对象 Process getProces

38、sById(String id); /根据流程 name获取流程定义对象 Process getProcessByName(String name); /根据流程 name、 version获取流程定义对象 Process getProcessByVersion(String name, Integer version); /根据给定的参数列表 args查询 process List getProcesss(QueryFilter filter); /根据给定的参数列表 args分页查询 process List getProcesss(Page page, QueryFilter filte

39、r); /根據 InputStream輸入流，部署流程定义 String deploy(InputStream input); /根據 InputStream輸入流，部署流程定义 void redeploy(String id, InputStream input); /卸载指定的流程定义，只更新状态 void undeploy(String id); 3. IOrderService: /* * 流程实例正常完成 * param orderId 流程实例 id */ void complete(String orderId); /* * 创建抄送实例 * param orderId 流程实例

40、 id * param actorIds 参与者 id * since 1.5 */ void createCCOrder(String orderId, String. actorIds); /* * 流程实例强制终止 * param orderId 流程实例 id */ void terminate(String orderId); /* * 流程实例强制终止 * param orderId 流程实例 id * param operator 处理人员 */ void terminate(String orderId, String operator); /* * 更新抄送记录为已阅 * p

41、aram orderId 流程实例 id * param actorIds 参与者 id */ void updateCCStatus(String orderId, String. actorIds); /* * 删除抄送记录 * param orderId 流程实例 id * param actorId 参与者 id */ void deleteCCOrder(String orderId, String actorId); 4. ITaskService: /完成指定的任务，删除活动任务记录，创建历史任务 Task complete(String taskId); /完成指定的任务，删除

42、活动任务记录，创建历史任务 Task complete(String taskId, String operator); /根据任务主键 ID，操作人 ID完成任务 Task complete(String taskId, String operator, Map args); /根据任务主键 ID，操作人 ID提取任务 Task take(String taskId, String operator); /向指定的任务 id添加参与者 void addTaskActor(String taskId, String. actors); /向指定的任务 id添加参与者 void addTaskA

43、ctor(String taskId, Integer performType, String. actors); /对指定的任务 id删除参与者 void removeTaskActor(String taskId, String. actors); /根据任务主键 id、操作人撤回任务 Task withdrawTask(String taskId, String operator); /* * 根据已有任务 id、任务类型、参与者创建新的任务 */ List createNewTask(String taskId, int taskType, String. actors); 5. IQ

44、ueryService: /* * 根据流程实例 ID获取流程实例对象 * param orderId 流程实例 id * return Order 流程实例对象 */ Order getOrder(String orderId); /* * 根据流程实例 ID获取历史流程实例对象 * param orderId 历史流程实例 id * return HistoryOrder 历史流程实例对象 */ HistoryOrder getHistOrder(String orderId); /* * 根据任务 ID获取任务对象 * param taskId 任务 id * return Task 任

45、务对象 */ Task getTask(String taskId); /* * 根据任务 ID获取历史任务对象 * param taskId 历史任务 id * return HistoryTask 历史任务对象 */ HistoryTask getHistTask(String taskId); /* * 根据任务 ID获取活动任务参与者数组 * param taskId 任务 id * return String 参与者 id数组 */ String getTaskActorsByTaskId(String taskId); /* * 根据任务 ID获取历史任务参与者数组 * param

46、 taskId 历史任务 id * return String 历史参与者 id数组 */ String getHistoryTaskActorsByTaskId(String taskId); /* * 根据 filter查询活动任务 * param filter 查询过滤器 * return List 活动任务集合 */ List getActiveTasks(QueryFilter filter); /* * 根据 filter分页查询活动任务 * param page 分页对象 * param filter 查询过滤器 * return List 活动任务集合 */ List getA

47、ctiveTasks(Page page, QueryFilter filter); /* * 根据 filter查询流程实例列表 * param filter 查询过滤器 * return List 活动实例集合 */ List getActiveOrders(QueryFilter filter); /* * 根据 filter分页查询流程实例列表 * param page 分页对象 * param filter 查询过滤器 * return List 活动实例集合 */ List getActiveOrders(Page page, QueryFilter filter); /* * 根

48、据 filter查询历史流程实例 * param filter 查询过滤器 * return List 历史实例集合 */ List getHistoryOrders(QueryFilter filter); /* * 根据 filter分页查询历史流程实例 * param page 分页对象 * param filter 查询过滤器 * return List 历史实例集合 */ List getHistoryOrders(Page page, QueryFilter filter); /* * 根据 filter查询所有已完成的任务 * param filter 查询过滤器 * return List 历史任务集合 */ List getHistoryTasks(QueryFilter filter); /* * 根据 filter分页查询已完成的历史任务 * param page 分页对象 * param filter 查询过滤器 * return List 历史任务集合 */ List getHistoryTasks(Page page, QueryFilter fil