The engine API is the most common way of interacting with Activiti. The central 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 1 of those for a whole server.
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();
1. ProcessEngine: The abstraction of the process engine, through which we can get all the services we need.
2. RepositoryService: Each different version of the business process definition in Activiti needs to use some definition files, deployment files and supporting data (such as BPMN2.0 XML files, form definition files, process definition image files, etc.), which are stored in the Activiti's built-in Repository. RepositoryService provides access to repository services.
3. RuntimeService: In Activiti, every time a process definition is started, a corresponding process object instance will be generated. RuntimeService provides functions such as starting a process, querying process instances, and setting and obtaining process instance variables. In addition, it provides access to process deployment, process definitions and process instances.
4. TaskService: Each execution node in the business process definition in Activiti is called a Task, and operations such as data access and state changes in the process need to be completed in the Task. TaskService provides operations related to user Task and Form. It provides runtime task query, collection, completion, deletion, and variable setting functions.
5.IdentityService: Activiti has built-in user and group management functions, and the information of these users and groups must be used to obtain the corresponding Task. IdentityService provides management functions for users and groups in the Activiti system.
6. ManagementService: ManagementService provides management and maintenance functions for the Activiti process engine. These functions are not used in workflow-driven applications and are mainly used for the daily maintenance of the Activiti system.
7. HistoryService: HistoryService is used to obtain information about running or completed process instances. Different from the process information obtained in RuntimeService, history information contains persistent information that has been persisted and has been optimized for queries.
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 withProcessEngines.init() and ProcessEngines.destroy().
The ProcessEngines class will scan for all activiti.cfg.xml and activiti-context.xml files. For allactiviti.cfg.xml files, the process engine will be built in the typical Activiti way:ProcessEngineConfiguration.createProcessEngineConfigurationFromInputStream(inputStream).buildProcessEngine(). For all activiti-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.
All services are stateless. This means that you can easily run Activiti 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.
The RepositoryService is probably the first service needed when working with the Activiti 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 BPMN 2.0 process. It is a representation of the structure and behaviour of each of the steps of a process. A deployment is the unit of packaging within the Activiti 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-processescould contain everything related to hr processes). The RepositoryService allows to 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.
Furthermore, this service allows 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 done on them, while activation is the opposite operation.
-
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.
While the RepositoryService is rather about static information (i.e. data that doesn’t change, or at least not a lot), theRuntimeService is quite the opposite. It deals with starting new process instances of process definitions. As said above, aprocess definition defines the structure and behaviour 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 which is used to retrieve and store process variables. This is data which is specific to the given process instance and can be used by various constructs in the process (e.g. an exclusive gateway often uses process variables to determine which path is chosen to continue the process). The Runtimeservice also allows 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 pointing 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 variouswait states and this service contains various operations to signal the instance that the external trigger is received and the process instance can be continued.
Tasks that need to be performed by actual human users of the system are core to a BPM engine such as Activiti. 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 instances.
-
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.
The IdentityService is pretty simple. It allows the management (creation, update, deletion, querying, …) of groups and users. It is important to understand that Activiti actually doesn’t do any checking on users at runtime. For example, a task could be assigned to any user, but the engine does not verify if that user is known to the system. This is because the Activiti engine can also be used in conjunction with services such as LDAP, Active Directory, etc.
The FormService is an optional service. Meaning that Activiti can perfectly be used 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. Activiti allows to define 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.
The HistoryService exposes all historical data gathered by the Activiti 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, etc. This service exposes mainly query capabilities to access this data.
The ManagementService is typically not needed when coding custom application using Activiti. It allows to retrieve information about the database tables and table metadata. Furthermore, it exposes query capabilities and management operations for jobs. Jobs are used in Activiti for various things such as timers, asynchronous continuations, delayed suspension/activation, etc. Later on, these topics will be discussed in more detail.
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.
The database names of Activiti all start with ACT_. The second part is a two-character identification of the use case of the table. This use case will also roughly match the service API.
ACT_RE_*: RE stands for repository. Tables with this prefix contain static information such as process definitions and process resources (images, rules, etc.).
ACT_RU_*: RU stands for runtime. These are the runtime tables that contain the runtime data of process instances, user tasks, variables, jobs, etc. Activiti only stores the runtime data during process instance execution, and removes the records when a process instance ends. This keeps the runtime tables small and fast.
ACT_ID_*: ID stands for identity. These tables contain identity information, such as users, groups, etc.
ACT_HI_*: HI stands for history. These are the tables that contain historic data, such as past process instances, variables, tasks, etc.
ACT_GE_*: general data, which is used in various use cases.