anchor.diff:  +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()+.
   
   
  -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.
  +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.
   
   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.
   
  -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 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 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+ 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
  +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.
  +
  +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 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), 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 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 various +wait 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 Flowable. Everything around tasks is grouped in the *TaskService*, such as
  +* 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.
  +
  +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 which 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.
  +
  +
  +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 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 Flowable 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 Flowable engine can also be used in conjunction with services such as LDAP, Active Directory, etc.
  -
  -The *FormService* is an optional service. Meaning that Flowable 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. Flowable 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 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, etc. This service exposes mainly query  capabilities to access this data.
  -
  -The *ManagementService* is typically not needed when coding custom application using Flowable. 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 Flowable 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 *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.
  +
  +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.
  +
  +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.
  +
  +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.
  +
  +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 link:$$flowable/index.html$$[the javadocs].
   
  
positive.code: }
  ----
  
  The +contextInitialized+ method will delegate to +ProcessEngines.init()+. That will look for +flowable.cfg.xml+ resource files on the classpath, and create a +ProcessEngine+ for the given configurations (e.g. multiple jars with a configuration file). If you have multiple such resource files on the classpath, make sure they all have different names. When the process engine is needed, it can be fetched using
  
  [source,java,linenums]
  ----
  
negative.code:     .list();
  ----
  
  Sometimes you need more powerful queries, for example, queries using an OR operator or restrictions you cannot express using the Query API. For these cases, we have native queries, which allow you to write your own SQL queries. The return type is defined by the Query object you use and the data is mapped into the correct objects (Task, ProcessInstance, Execution, ...). Since the query will be fired at the database you have to use table and column names as they are defined in the database; this requires some knowledge about the internal data structure and it is recommended to use native queries with care. The table names can be retrieved through the API to keep the dependency as small as possible.
  
  [source,java,linenums]
  ----
  