Flowable 6.6.0 BPMN用户指南 - (3) The Flowable API - 3.1 流程引擎API和服务

《Flowable 6.6.0 BPMN用户指南》

1. 入门

2. 配置

3 The Flowable API

3.1 流程引擎API和服务
3.2 异常策略
3.3 查询API（Query API）
3.4 变量（Variables）
3.5 瞬态变量（Transient variables）
3.6 表达式（Expressions）
3.7 表达式函数（Expression functions）
3.8 单元测试
3.9 单元测试调试
3.10 Web应用程序中的流程引擎

Flowable 6.6.0 用户指南相关文档下载

• BPMN用户指南 第一部分 - 中文PDF精编版
• BPMN用户指南 第二部分 - 中文PDF精编版
• BPMN用户指南 第三部分 - 中文PDF精编版
• 应用程序指南 - 中文PDF精编版
• 应用程序指南 - 中英对照PDF精编版
• 应用程序指南 - Eclipse设计器中文PDF精编版
• 表单用户指南 - 中文PDF精编版
• 事件注册表用户指南 - 中文PDF精编版

---

有关Flowable文档的其他资料，参见：

《Flowable文档大全》

3 The Flowable API

3.1 流程引擎API和服务

The engine API is the most common way of interacting with Flowable. The main starting point is the ProcessEngine, which can be created in several ways as described in the configuration section. From the ProcessEngine, you can obtain the various services that contain the workflow/BPM methods. ProcessEngine and the services objects are thread safe, so you can keep a reference to one of those for a whole server.

与Flowable交互的最常见方式是引擎API。主要的起点是ProcessEngine，它可以通过几种方式创建（将配置部分中描述）。通过ProcessEngine，您可以获取包含工作流/BPM方法的各种服务。ProcessEngine和service对象是线程安全的，因此可以为整个服务器保留对其中一个对象的引用。

ProcessEngine processEngine = ProcessEngines.getDefaultProcessEngine();

RuntimeService runtimeService = processEngine.getRuntimeService();
RepositoryService repositoryService = processEngine.getRepositoryService();
TaskService taskService = processEngine.getTaskService();
ManagementService managementService = processEngine.getManagementService();
IdentityService identityService = processEngine.getIdentityService();
HistoryService historyService = processEngine.getHistoryService();
FormService formService = processEngine.getFormService();
DynamicBpmnService dynamicBpmnService = processEngine.getDynamicBpmnService();

ProcessEngines.getDefaultProcessEngine() will initialize and build a process engine the first time it is called and afterwards always return the same process engine. Proper creation and closing of all process engines can be done with ProcessEngines.init() and ProcessEngines.destroy().

ProcessEngines.getDefaultProcessEngine()将在流程引擎被第一次调用时初始化并创建，然后始终返回相同的流程引擎。可通过ProcessEngines.init()和ProcessEngines.destroy ()正确创建和关闭流程引擎。

The ProcessEngines class will scan for all flowable.cfg.xml and flowable-context.xml files. For all flowable.cfg.xml files, the process engine will be built in the typical Flowable way: ProcessEngineConfiguration.createProcessEngineConfigurationFromInputStream(inputStream).buildProcessEngine(). For all flowable-context.xml files, the process engine will be built in the Spring way: first the Spring application context is created and then the process engine is obtained from that application context.

ProcessEngines类将扫描所有flowable.cfg.xml和flowable-context.xml文件。对所有flowable.cfg.xml文件，流程引擎将以典型的Flowable方式构建：

ProcessEngineConfiguration.createProcessEngineConfigurationFromInputStream(inputStream).buildProcessEngine()。对所有flowable-context.xml文件，流程引擎将以Spring方式构建：首先创建Spring应用程序上下文，然后从该应用程序上下文获取流程引擎。

All services are stateless. This means that you can easily run Flowable on multiple nodes in a cluster, each going to the same database, without having to worry about which machine actually executed previous calls. Any call to any service is idempotent regardless of where it is executed.

所有服务都是无状态的。这意味着您可以轻松地在集群中的多个节点上运行Flowable，每个节点都指向同一个数据库，而不必担心哪个机器实际执行了以前的调用。对任何服务的任何调用都是幂等的，而不管它在哪里执行。

The RepositoryService is probably the first service needed when working with the Flowable engine. This service offers operations for managing and manipulating deployments and process definitions. Without going into much detail here, a process definition is a Java counterpart of the BPMN 2.0 process. It is a representation of the structure and behavior of each of the steps of a process. A deployment is the unit of packaging within the Flowable engine. A deployment can contain multiple BPMN 2.0 XML files and any other resource. The choice of what is included in one deployment is up to the developer. It can range from a single process BPMN 2.0 XML file to a whole package of processes and relevant resources (for example, the deployment ‘hr-processes’ could contain everything related to HR processes). The RepositoryService can deploy such packages. Deploying a deployment means it is uploaded to the engine, where all processes are inspected and parsed before being stored in the database. From that point on, the deployment is known to the system and any process included in the deployment can now be started.

RepositoryService（存储服务）可能是使用Flowable引擎时需要的第一个服务。此服务提供用于对部署、流程定义进行管理和操作的操作。这里不需要详细说明，流程定义是BPMN 2.0流程的Java对应物。它是流程中每个步骤的结构和行为的表示。部署是Flowable引擎中的打包单元。一个部署可以包含多个BPMN 2.0 XML文件和任何其他资源。一个部署中包含的内容由开发人员决定。它可以从单个流程BPMN 2.0 XML文件到整个流程包和相关资源（例如，部署“hr-processes”可以包含与hr流程相关的所有内容）。RepositoryService可以部署这样的包。执行部署意味着部署文件被上载到引擎，在存储到数据库之前所有流程都会被进行检查和解析。从此时起，系统就知晓部署了，现在可以启动部署中包含的流程了。

Furthermore, this service allows you to:

• Query on deployments and process definitions known to the engine.
• Suspend and activate deployments as a whole or specific process definitions. Suspending means no further operations can be performed on them, while activation is the opposite and enables operations again.
• Retrieve various resources, such as files contained within the deployment or process diagrams that were auto-generated by the engine.
• Retrieve a POJO version of the process definition, which can be used to introspect the process using Java rather than XML.

此外，此服务还允许您：

• 查询引擎已知的部署和流程定义。
• 挂起和激活全部部署或特定流程定义的部署。挂起意味着不能对它们执行进一步的操作，而激活则相反，会再次启用操作。
• 检索各种资源，例如部署图或流程图中包含的、由引擎自动生成的文件。
• 检索流程定义的POJO版本，该版本可用于使用Java而不是XML来检查流程。

While the RepositoryService is mostly about static information (data that doesn’t change, or at least not a lot), the RuntimeService is quite the opposite. It deals with starting new process instances of process definitions. As said above, a process definition defines the structure and behavior of the different steps in a process. A process instance is one execution of such a process definition. For each process definition there typically are many instances running at the same time. The RuntimeService also is the service that is used to retrieve and store process variables. This is data that is specific to the given process instance and can be used by various constructs in the process (for example, an exclusive gateway often uses process variables to determine which path is chosen to continue the process). The Runtimeservice also allows you to query on process instances and executions. Executions are a representation of the ‘token’ concept of BPMN 2.0. Basically, an execution is a pointer to where the process instance currently is. Lastly, the RuntimeService is used whenever a process instance is waiting for an external trigger and the process needs to be continued. A process instance can have various wait states and this service contains various operations to ‘signal’ to the instance that the external trigger is received and the process instance can be continued.

虽然RepositoryService主要是关于静态信息的（没有变化的数据，或者至少没有很多变化），但是RuntimeService（运行时服务） 恰恰相反。它处理启动某个流程定义的一个新流程实例。如上所述，流程定义定义了流程中步骤的结构和行为。流程实例则是流程定义的一个执行。对于每个流程定义，通常有多个实例同时运行。RuntimeService也是用于检索和存储流程变量（process variable）的服务。流程变量是与指定流程实例相关的数据，可由流程中的各种构造使用（例如，独占网关通常使用流程变量来确定选择哪个路径来继续流程）。RuntimeService还允许您查询流程实例及其执行情况。执行（Execution）是BPMN 2.0的“令牌”(‘token’)概念的表示。基本上，执行是指向流程实例当前所在位置的指针。最后，每当流程实例等待外部触发器并且流程需要继续时，就会使用RuntimeService。流程实例可以有各种等待状态，并且该服务包含各种操作，以向实例发出“信号”，表示已接收到外部触发器，流程实例可以继续。

Tasks that need to be performed by human users of the system are core to a BPM engine such as Flowable. Everything around tasks is grouped in the TaskService, such as:

• Querying tasks assigned to users or groups
• Creating new standalone tasks. These are tasks that are not related to a process instance.
• Manipulating to which user a task is assigned or which users are in some way involved with the task.
• Claiming and completing a task. Claiming means that someone decided to be the assignee for the task, meaning that this user will complete the task. Completing means ‘doing the work of the tasks’. Typically this is filling in a form of sorts.

需要由系统的人类用户执行的任务是BPM引擎（如Flowable）的核心。任务相关的所有内容都组合在TaskService（任务服务）中，例如：

• 查询分配给用户或组的任务
• 创建新的独立（standalone ）任务。这些任务与流程实例无关。
• 操纵任务分配给哪个用户或哪些用户以某种方式参与任务。
• 认领并完成任务。认领意味着某人决定成为任务的受让人，这意味着这个用户将完成任务。完成意味着“完成任务”。通常是填写某种形式的表单。

The IdentityService is pretty simple. It supports the management (creation, update, deletion, querying, …) of groups and users. It is important to understand that Flowable actually doesn’t do any checking on users at runtime. For example, a task could be assigned to any user, but the engine doesn’t verify whether that user is known to the system. This is because the Flowable engine can also be used in conjunction with services such as LDAP, Active Directory, and so on.

IdentityService （身份服务）非常简单。IdentityService 支持组和用户的管理（创建、更新、删除、查询等）。重要的是要理解Flowable实际上在运行时不对用户执行任何检查。例如，任务可以分配给任何用户，但引擎不会验证系统是否知道该用户。这是因为Flowable引擎还可以与LDAP、Active Directory等服务结合使用。

The FormService is an optional service. Meaning that Flowable can be used quite happily without it, without sacrificing any functionality. This service introduces the concept of a start form and a task form. A start form is a form that is shown to the user before the process instance is started, while a task form is the form that is displayed when a user wants to complete a form. Flowable allows the specification of these forms in the BPMN 2.0 process definition. This service exposes this data in an easy way to work with. But again, this is optional, as forms don’t need to be embedded in the process definition.

FormService （表单服务）是可选服务。这意味着Flowable在没有它的情况下可以非常愉快地使用，而不会牺牲任何功能。这个服务引入了开始表单（start form）和任务表单（task form）的概念。开始表单是在流程实例启动之前向用户显示的表单，而任务表单是在用户希望完成表单时显示的表单。Flowable允许在BPMN 2.0流程定义中指定这些表单。使用此服务可以轻松地暴露数据。但是，这也是可选的，因为表单不需要嵌入到流程定义中。

The HistoryService exposes all historical data gathered by the Flowable engine. When executing processes, a lot of data can be kept by the engine (this is configurable), such as process instance start times, who did which tasks, how long it took to complete the tasks, which path was followed in each process instance, and so on. This service exposes mainly query capabilities to access this data.

HistoryService （历史服务）公开Flowable引擎收集的所有历史数据。在执行流程时，引擎可以保存大量数据（这是可配置的），例如流程实例的开始时间、谁执行了哪些任务、完成任务所用的时间、每个流程实例流转的路径等等。此服务主要暴露访问此数据的查询功能。

The ManagementService is typically not needed when coding custom application using Flowable. It allows the retrieval of information about the database tables and table metadata. Furthermore, it exposes query capabilities and management operations for jobs. Jobs are used in Flowable for various things, such as timers, asynchronous continuations, delayed suspension/activation, and so on. Later on, these topics will be discussed in more detail.

在使用Flowable编写自定义应用程序时，通常不需要ManagementService （管理服务）。它允许检索有关数据库表和表元数据的信息。此外，它还提供了作业的查询功能和管理操作。作业在Flowable中用于各种功能，例如定时器、异步持续、延迟暂停/激活等等。稍后，将更详细地讨论这些主题。

The DynamicBpmnService can be used to change part of the process definition without needing to redeploy it. You can, for example, change the assignee definition for a user task in a process definition, or change the class name of a service task.

For more detailed information on the service operations and the engine API, see the javadocs.

DynamicBpmnService （动态BPMN服务）可用于变更流程定义的部分信息，而无需重新部署它。例如，您可以在流程定义中变更用户任务的受让人定义（assignee definition），或变更服务任务（service task）的类名。

有关服务操作和引擎API的更多详细信息，请参阅javadocs。

---

培训视频推荐

CSDN上提供了Flowable 6.6.0的系列培训视频课程，欢迎有兴趣的朋友前往学习。

• 《Flowable流程入门课程》
• 《Flowable流程高级课程》
• 《Flowable从入门到精通》