fire-workflow开发手册.doc

Fire Workflow开发手册1.01. 框架说明1.1. 基础说明阅读本文档前请确认已经阅读过下面两篇文档，并对该两篇文档有了较深刻的认识。l WSI开发手册1.0.docl 99_FireWorkflow工作流原理、设计与应用.pdfFire Workflow是由国人开发的一个开源工作流引擎，可以解决常见的带有工作流需求的案例。本文的编写目的是让读者能快速的基于Fire Workflow进行工作流相关开发。1.2. 基础设施本系统的主体开发框架是WebWork + Spring + iBatis，在这之上引入Fire WorkFlow引擎。 1.3. 框架结构由于框架是基于WSI框架的，因此这里的编码结构和原来的WSI的编码风格完全一致。2. 工作步骤2.1. 工作步骤总体介绍要做Fire Workflow相关的开发，大约需要做以下的工作。1. 配置Fire Workflow环境2. 业务流程数据库设计3. 画流程图4. 编写流程执行者Handler5. 在业务代码中加入流程代码2.2. 配置Fire Workflow环境Fire Workflow所需要用到的东西可以在公司的KM下找到。Jar包和脚本等在fireflow例子.zip里都能找到。最新的fireworkflow的jar包请关注公司最新发布的，或者询问公司系统架构师。2.2.1. 导入Fire Workflow的jar包将Fire Workflow（本jar请使用公司最新发布的）及其需要使用的第三方jar包导入到业务系统工程里，注意不要和工程里已有的jar冲突：拷贝以上jar包至项目的Web-INF/lib目录下，并配置好build path。2.2.2. 在数据库中执行Fire Workflow流程库脚本由于Fire Workflow采取了业务和流程完全分离的模式，因此程序编写人员并不需要关注流程引擎的工作细节，但是流程引擎需要使用自己的流程表，因此流程库的脚本还是需要执行的。这些脚本创建的7张流程表为：l t_ff_rt_workitem;l t_ff_rt_token;l t_ff_rt_taskinstance;l t_ff_rt_procinst_var;l t_ff_rt_processinstance;l t_ff_hist_trace;l t_ff_df_workflowdef;这7张表的关系，详见99_FireWorkflow工作流原理、设计与应用.pdf，这里就不赘述了。2.2.3. 配置文件我们需要拷贝spring配置文件到系统目录下：接下来，我们配置Ibatis的sql map config，设置流程库的7张表。这些sql的xml文件已经包含在了Fire Workflow的jar里了。2.2.4. 配置流程设计器eclipse插件在KM里导出FireflowDesigner4Eclipse_1.0.0_beta_build090723.jar，然后将这个jar放在eclipse的plugins目录下，重启eclipses。2.3. 业务流程数据库设计由于Fire Workflow采取了业务和流程完全分离的模式，因此流程库和业务库的关联关系通常有两种方式。一是在业务库里添加流程库的关联字段，二是在流程库里添加业务库的字段。由于Fire Workflow自己对流程库进行管理操作，我们应当避免直接修改流程库。因此我们选择第一种方式，在业务库添加流程库的关联字段。由于流程实例信息基本可以拿到一个流程的所有的信息，因此我们在设计的时候，可以在相关的业务表里关联流程实例表的主键，如下图的例子。2.4. 画流程图在画流程图之前，确保已经正确的安装了流程设计器。主要步骤如下：画流程图，请主要参考99_FireWorkflow工作流原理、设计与应用.pdf，这里就不赘述了。一个画好的请假流程图如下。2.4.1. 设置流程执行Handler需要注意的是，每个task里的workitem可以指定执行者，这个是通过handler来指定的，下一节我们将介绍Handler的代码的编写。2.4.2. 设置流程执行相关参数在流程的流转里，我们通常可能会用到各种参数。具体参数的设置方法比较简单。然后我们可以在流程的流转连接线处，设置流转条件，表达式里可以直接使用上面设置的参数。表达式是按照Expression Language表达式的规则来的。提醒一点，流程库里参数value使用的字段是varchar2。而我们使用的ibatis，在映射boolean型参数值到数据库的varchar2字段的时候，会自动转成1和0。因此建议原本要使用boolean型参数的地方true和false，都用Integer的1和0代替。2.4.3. 绑定流程图到程序里程序读取我们所设计的流程图有两种方式，一种是直接读xml，一种是从DB里读取T_FF_DF_WORKFLOWDEF这张表。直接读xml的方式比较简单。打开applicationContext-fireflow-engine.xml，设置definitionService为DefinitionService4FileSystem。然后配置要读取的xml。如果要读取数据库T_FF_DF_WORKFLOWDEF表的方式。则配置definitionService为DefinitionService4DBMS。数据库里的字段设置也比较简单。几个比较关键的字段，其中PROCESS_CONTENT是放整个流程定义xml的全部内容。VERSION字段提供了同一个流程定义的多个版本的实现。而PROCESS_ID则是这个流程定义的标识。2.5. 编写流程执行者Handler上一节提到流程的执行者是通过Handler来实现的。那么我们如何编写Handler呢。首先我们介绍一下编写最简单的handler，后面我们将介绍直接使用系统封装的handler（不用编写java代码）。对于自己编写一个最简单的handler，首先我们可以在代码目录下建一个编写handler的包，如下所示：然后再在里面编写Handler。2.5.1. 实现IAssignmentHandler接口所有的Handler必须实现IAssignmentHandler接口，这样，流程引擎才可以正常使用。以下为一个例子。assign方法有两个参数，一个是assignable，这个其实是task instance实例，可以直接转化成task instance。然后继而可以拿到流程实例的相关信息。assignable有一个方法assignToActor(String actorId)可以指定分配工作项给单个用户ID，还有一个方法assignToActors(List actors)可以分配给多个用户。而下图表示了如何设置一个人完成即可，还是需要全部用户都完成，才可完成该项任务。另一个参数是performerName，这个是在画流程定义图的时候指定的。在实际应用中，我们可以指定角色名为这个Name，然后在程序里可以拿到角色名，继而根据角色拿到多个用户，进而做进一步设置。如果在Handler里要使用数据库操作，我们还可以使Handler继承我们的base service的实现类，或者fireflow Service的实现类。后面会提到fire flow Service的实现类其实也是继承于Base service的实现类，其中多加了一个runtimeContext属性，这个runtimeContext是Fire Workflow引擎调用的一个接入口。以下为继承FireflowServiceImpl的例子。这样，在spring配置文件里设置注入dao，runtimeContext等bean后，handler里就可以使用ibatis接口或者工作流引擎接口做更多的事情。2.5.2. 在Spring配置文件里配置HandlerHandler必须在spring配置文件里配置后，才能被工作流引擎所使用。首先我们新建一个spring配置文件。然后在里面添加Handler的配置。这些handler就是在画流程定义图的时候指定的。如果handler继承了BaseServiceImpl或者FireflowServiceImpl了，那么在handler的配置里还需要加入dao, utilservice, runtimeContext等属性配置。这个配置方法同业务系统service配置类似。2.5.3. 使用系统封装的SimpleHandlerImpl在fire workflow框架里，系统封装了一个通用的handler，其java类的全称为com.broadtext.framework.handler.SimpleHandlerImpl。目前，SimpleHandlerImpl支持3种常见的操作人userName：用户登录名 roleName：角色名称 processCreator：流程创建人。同时，还支持流程参数动态传入。如果采用这种方式，则不需要编写Handler的java代码，只需要通过配置文件来编写就可以了。2.5.3.1. userNameuserName的方式，是指在流程定义的时候环节执行的Performer的Name指定成固定用户的名称或者账户名。以下是一个典型的userName方式的配置。下图红框的部分，定义了这个SimpleHandlerImpl的执行人类型是userName。篮框的部分指定了根据userName查找userId的ibatisSql的id。如果系统中已有，直接把id定义在这里即可。如果系统中没有这个sql，则开发者可以在任意的ibatis sql文件里加入一个这样的查询sql即可。这个sql返回的类型应该是字符串（java.lang.String），即userId，当然根据业务需要也可以是employeeId，或者其他的user唯一标识。这里这个user的唯一标识，将在handler触发后，生成t_ff_rt_workitem表记录的时候，保存在actor_id字段中。以下是该handler关于userName类型的控制。可以看到，程序是先通过ibatis dao查询出actorId，然后assign给了相关工作项。2.5.3.2. roleNameroleName的方式和userName的方式类似。是指在流程定义的时候环节执行的Performer的Name指定成固定角色的名称。具体配置也很类似。如下图，只是要注意的是这里querySqlId应该是对应的跟据roleName查询userId的sql id。因为角色可以对应多个用户，因此这里assign的是多个用户。而完成流程是否需要assign的所有用户都完成，还是assign的用户中任意一个人完成即可，请参看2.5.1中的描述。同样，以下是该handler关于roleName类型的控制。2.5.3.3. proceseeCreatorprocessCreator的方式是指采用流程创建者作为某一环节的执行人的方式。这种方式比较简单，通常流程开始后的第一个环节就是采用这种设置。这种方式不需要sql查询，因此配置比较简单，如下所示：以下是handler关于processCreator类型的控制。2.5.3.4. 自定义类型以上3种类型是SimpleHandlerImpl提供的默认的3种类型。开发人员也可以自己定义新的类型。系统默认预留了扩展的方法，只要继承SimpleHandlerImpl，并重写如下的方法，就可以简单的实现扩展。以下是一个actorId类型的例子，继承了SimpleHandlerImpl并采用了自定义的方式。实际应用中也可以使用这个例子，这个类的完全路径加全名是：com.broadtext.framework.handler.ActorIdHandlerImpl但由于是直接传入id不太好，因此最好结合2.5.3.5里介绍的动态传入的方式使用。2.5.3.5. 流程参数动态传入SimpleHandlerImpl还支持流程参数动态传入，也就是说，在Performer的Name里可以直接填流程里某个具体参数的名字。在SimpleHandlerImpl里，程序会先根据这个参数拿到参数值，再进行相关的转化。流程参数动态传入的方式，支持上面介绍的所有3种类型和自定义类型。源代码中是这样实现的：在spring配置文件里，只要添加isVaribles参数，并设置成true即可。2.5.3.6. 自动完成自动完成参数一般是指定了某个类型的执行人，但是又不需要执行人自己去操作的情况（不同于那种不需要人完成的自动环节）。一般用的最多的是流程创建者，流程创建者创建流程后，通常第一个环节就是流程创建者自己做的，并且是自动完成的。具体实例配置如下。默认的SimpleHandlerImpl对userName和processCreator支持这种自动完成的方式。另外ActorIdHandlerImpl也支持这种自动完成的方式。2.6. 在业务代码中加入流程代码业务代码里我们常用到的调用工作流接口的地方，主要是启动工作流，查询我要做的工作列表，查询我完成的工作列表，完成工作项，添加工作流程参数等等。以下就主要介绍一下这几个方面。其他更多的请查阅Fire Workflow的文档和API。首先业务service如果要调用工作流引擎，请继承FireflowServiceImpl而不是BaseServiceImpl，这个和前面Handler那里的说明类似。然后spring配置文件中多加一个runtimeContext的属性。常用的方法都封装在了FireflowServiceImpl中。2.6.1. 启动工作流启动工作流，在这里主要就是创建一个新的流程实例，并自动启动，然后返回该流程实例的唯一ID。创建流程的代码很简单，直接在service里调用FireflowServiceImpl如下的两个方法任意一个方法即可（第二个方法顺带着设置一些流程参数），如下所示。这样流程实例的唯一ID，就可以获得并保存在我们的业务库里了。在流程被创建并且完成后，流程会自动进入第一个流程环节。一般第一个流程环节的Hanlder里都是设置成了直接完成工作内容，例如下面的例子，我们可以根据流程实例的创建人的id来分配给第一个流程环节，并直接签收完成。这样的好处是很明显的，由于我们业务系统通常都是在执行第一步的时候需要启动流程，也就是说，创建流程和执行第一步的通常都是同一个人。因此这里流程启动后，直接就将第一个步骤同时也一并完成掉的。我们也可以不写java代码，而直接使用SimpleHandlerImpl，详见2.5.3节。2.6.2. 查询我待办的工作列表在流程的创建者创建完成后，流程会走入到后续的环节中。后续的人如何去签收完成工作呢？一般来说，在业务系统里会先提供一个查询Todo的工作列表的功能，然后在这个工作列表里挑选要完成的工作，再进行下一步操作。框架提供了一个简单的查询Todo的工作列表的方法，这个方法不牵涉到业务表里的数据，只是拿出流程表里最简单的数据。使用框架的方法比较简单，直接在service里调用基类的如下方法即可（这里的List里包含的对象的类型是com.broadtext.framework.domain.WorkItem）：对于复杂的查询Todo的工作列表，可能会涉及到几张表，而且一般需要涉及到显示业务表中的一些数据。其中流程库里的表主要提供查询条件检索，比如：等待我完成的这个条件。而真正在业务系统里要显示的表的内容，可能就是我们之前提到的关联了流程实例ID的表。例如，审批假单，可能就需要把业务库里的请假表也查出来，这样就可以知道是谁请的假，请假类型，请假时间等等。以下为一个例子。翻页列表action和普通的翻页列表action类似，这里就不介绍了。但是调用的service的得到Page的方法，可以由我们自己定义。例如：在ibatis的sql的xml文件里，我们用业务库的表联查流程库表。例如：这里我们联查了流程实例，任务和工作项三张流程库的表。在下面的查询条件里，有workitemStatus和processInstanceStatus这两个属性。通过设置这两个属性，可以得到不同的查询结果。例如，workitemStatus设置为1，表示为running，即将需要做的。关于workitem的status和process instance的status值，参考如下：IWorkitem里的定义： public static final int INITIALIZED = 0; public static final int RUNNING = 1; public static final int COMPLETED = 7; public static final int CANCELED = 9;IProcessInstance里的定义： public static final int INITIALIZED = 0; public static final int RUNNING = 1; public static final int COMPLETED = 7; public static final int CANCELED = 9;2.6.3. 查询我完成的工作列表查询完成的工作列表与上面查询将要做的工作类似，对于简单的查询流程库里的信息，框架提供了一个简单的查询方法（同查询待办的一样，这里的List里包含的对象的类型是com.broadtext.framework.domain.WorkItem）。同样对于需要查询业务库的复杂的查询，只是这里传入的workitemStatus应该是7，即comp