### Initialize and Run BPMN Example

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/zh_CN/bpmn/ch07a-BPMN-Introduction.adoc

A complete Java example demonstrating the initialization of the Flowable ProcessEngine, deployment of a BPMN resource, and starting a process instance.

```java
public static void main(String[] args) {

  // 创建Flowable流程引擎
  ProcessEngine processEngine = ProcessEngineConfiguration
    .createStandaloneProcessEngineConfiguration()
    .buildProcessEngine();

  // 获取Flowable服务
  RepositoryService repositoryService = processEngine.getRepositoryService();
  RuntimeService runtimeService = processEngine.getRuntimeService();

  // 部署流程定义
  repositoryService.createDeployment()
    .addClasspathResource("FinancialReportProcess.bpmn20.xml")
    .deploy();

  // 启动流程实例
  runtimeService.startProcessInstanceByKey("financialReport");
}
```

--------------------------------

### Full BPMN Tutorial Example

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/zh_CN/bpmn/ch07a-BPMN-Introduction.adoc

A comprehensive Java example demonstrating the Flowable API for creating a process engine, deploying a BPMN model, starting a process instance, handling tasks, and querying process history.

```java
public class TenMinuteTutorial {

  public static void main(String[] args) {

    // 创建Flowable流程引擎 
    ProcessEngine processEngine = ProcessEngineConfiguration
      .createStandaloneProcessEngineConfiguration()
      .buildProcessEngine();

    // 获取Flowable服务
    RepositoryService repositoryService = processEngine.getRepositoryService();
    RuntimeService runtimeService = processEngine.getRuntimeService();

    // 部署流程定义
    repositoryService.createDeployment()
      .addClasspathResource("FinancialReportProcess.bpmn20.xml")
      .deploy();

    // 启动流程实例
    String procId = runtimeService.startProcessInstanceByKey("financialReport").getId();

    // 获取第一个任务
    TaskService taskService = processEngine.getTaskService();
    List<Task> tasks = taskService.createTaskQuery().taskCandidateGroup("accountancy").list();
    for (Task task : tasks) {
      System.out.println("Following task is available for accountancy group: " + task.getName());

      // 申领任务
      taskService.claim(task.getId(), "fozzie");
    }

    // 验证Fozzie获取了任务
    tasks = taskService.createTaskQuery().taskAssignee("fozzie").list();
    for (Task task : tasks) {
      System.out.println("Task for fozzie: " + task.getName());

      // 完成任务
      taskService.complete(task.getId());
    }

    System.out.println("Number of tasks for fozzie: "
            + taskService.createTaskQuery().taskAssignee("fozzie").count());

    // 获取并申领第二个任务
    tasks = taskService.createTaskQuery().taskCandidateGroup("management").list();
    for (Task task : tasks) {
      System.out.println("Following task is available for management group: " + task.getName());
      taskService.claim(task.getId(), "kermit");
    }

    // 完成第二个任务并结束流程
    for (Task task : tasks) {
      taskService.complete(task.getId());
    }

    // 验证流程已经结束
    HistoryService historyService = processEngine.getHistoryService();
    HistoricProcessInstance historicProcessInstance =
      historyService.createHistoricProcessInstanceQuery().processInstanceId(procId).singleResult();
    System.out.println("Process instance end time: " + historicProcessInstance.getEndTime());
  }

}
```

--------------------------------

### Start Process Instance Success Response Body

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/zh_CN/bpmn/ch14-REST.adoc

Example JSON response when a process instance is successfully created.

```json
{
   "id":"7",
   "url":"http://localhost:8182/runtime/process-instances/7",
   "businessKey":"myBusinessKey",
   "suspended":false,
   "processDefinitionUrl":"http://localhost:8182/repository/process-definitions/processOne%3A1%3A4",
   "activityId":"processTask",
   "tenantId" : null
}
```

--------------------------------

### Get Start Form Model

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/en/bpmn/ch08-Forms.adoc

Retrieves the form model for starting a process instance. Use when a process definition has a start form.

```java
FormModel RuntimeService.getStartFormModel(String processDefinitionId, String processInstanceId)
```

--------------------------------

### Start Process Instance by Key

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/zh_CN/bpmn/ch07a-BPMN-Introduction.adoc

Starts a new process instance using the key of a deployed process definition. The process execution begins at the start event.

```java
ProcessInstance processInstance = runtimeService.startProcessInstanceByKey("financialReport");
```

--------------------------------

### Start Process Instance with Form

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/en/bpmn/ch08-Forms.adoc

Starts a process instance using a start form definition. All form values must be passed in the variables map.

```java
ProcessInstance RuntimeService.startProcessInstanceWithForm(String processDefinitionId, String outcome, 
    Map<String, Object> variables, String processInstanceName)
```

--------------------------------

### Start a Process Instance

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/en/bpmn/ch02-GettingStarted.adoc

Starts a new process instance using a process definition key and an optional map of initial process variables.

```APIDOC
## Start a Process Instance

### Description
Starts a new process instance based on a process definition key and provides initial process variables.

### Method
POST

### Endpoint
/service/runtime/process-instances

### Parameters
#### Request Body
- **processDefinitionKey** (string) - Required - The key of the process definition to use.
- **variables** (array) - Optional - A list of initial process variables.
  - **name** (string) - The name of the variable.
  - **value** (any) - The value of the variable.

### Request Example
```bash
curl --user rest-admin:test -H "Content-Type: application/json" -X POST -d '{ "processDefinitionKey":"holidayRequest", "variables": [ { "name":"employee", "value": "John Doe" }, { "name":"nrOfHolidays", "value": 7 }]}' http://localhost:8080/flowable-rest/service/runtime/process-instances
```

### Response
#### Success Response (200)
A JSON object representing the newly created process instance.
```

--------------------------------

### Starting a Process Instance by Message

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/zh_CN/bpmn/ch07b-BPMN-Constructs.adoc

You can start a new process instance by sending a message.

```APIDOC
## Starting a Process Instance by Message

If a message needs to start a new process instance, you can use one of the methods provided by the runtime service:

### Method
`ProcessInstance startProcessInstanceByMessage(String messageName)`
`ProcessInstance startProcessInstanceByMessage(String messageName, Map<String, Object> processVariables)`
`ProcessInstance startProcessInstanceByMessage(String messageName, String businessKey, Map<String, Object> processVariables)`

**Description:**
These methods initiate a process instance using the provided message name and optional process variables and business key.
```

--------------------------------

### Start a Process Instance

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/en/bpmn/ch02-GettingStarted.adoc

Initiate a new process instance using its key and providing initial process variables as a JSON payload. This command starts a specific process definition.

```bash
curl --user rest-admin:test -H "Content-Type: application/json" -X POST -d '{ "processDefinitionKey":"holidayRequest", "variables": [ { "name":"employee", "value": "John Doe" }, { "name":"nrOfHolidays", "value": 7 }]}' http://localhost:8080/flowable-rest/service/runtime/process-instances
```

--------------------------------

### Example BPMN 2.0 Process Definition

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/en/bpmn/ch05a-Spring-Boot.adoc

A basic BPMN 2.0 process definition with a start event, a user task, and an end event. This file should be placed in the 'processes' folder for automatic deployment.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<definitions
        xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
        xmlns:flowable="http://flowable.org/bpmn"
        targetNamespace="Examples">

    <process id="oneTaskProcess" name="The One Task Process">
        <startEvent id="theStart" />
        <sequenceFlow id="flow1" sourceRef="theStart" targetRef="theTask" />
        <userTask id="theTask" name="my task" />
        <sequenceFlow id="flow2" sourceRef="theTask" targetRef="theEnd" />
        <endEvent id="theEnd" />
    </process>

</definitions>
```

--------------------------------

### Get Users Authorized to Start a Process Definition

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/zh_CN/bpmn/ch07b-BPMN-Constructs.adoc

Query for users who are configured as potential starters for a specific process definition using the identityService. This is useful for authorization checks.

```java
List<User> authorizedUsers = identityService().createUserQuery()
    .potentialStarter("processDefinitionId")
    .list();
```

--------------------------------

### Retrieve Startable Process Definitions by User

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/en/bpmn/ch07b-BPMN-Constructs.adoc

This Java code snippet demonstrates how to query the Flowable engine to get a list of process definitions that a specific user is authorized to start.

```java
processDefinitions = repositoryService.createProcessDefinitionQuery().startableByUser("userxxx").list();
```

--------------------------------

### Multi-Instance Sub-Process with Execution Listeners

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/zh_CN/bpmn/ch07b-BPMN-Constructs.adoc

An example of a sub-process configured for multi-instance execution, including execution listeners for its start and end events. This demonstrates how listeners are invoked at different stages of the multi-instance lifecycle.

```xml
<subProcess id="subprocess1" name="Sub Process">
  <extensionElements>
    <flowable:executionListener event="start" class="org.flowable.MyStartListener"/>
    <flowable:executionListener event="end" class="org.flowable.MyEndListener"/>
  </extensionElements>
  <multiInstanceLoopCharacteristics isSequential="false">
    <loopDataInputRef>assignees</loopDataInputRef>
    <inputDataItem name="assignee"></inputDataItem>
  </multiInstanceLoopCharacteristics>
  <startEvent id="startevent2" name="Start"></startEvent>
  <endEvent id="endevent2" name="End"></endEvent>
  <sequenceFlow id="flow3" name="" sourceRef="startevent2" targetRef="endevent2"></sequenceFlow>
</subProcess>
```

--------------------------------

### Starting a Case Instance by Key

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/zh_CN/cmmn/ch05-Deployment.adoc

Demonstrates how to start a CMMN case instance using its definition key. Flowable will automatically select the latest deployed version of the case definition.

```java
runtimeService.createCaseInstanceBuilder().caseDefinitionKey("myCase").start()

```

--------------------------------

### Start Process Instance via API

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/en/bpmn/ch07b-BPMN-Constructs.adoc

This Java code snippet demonstrates starting a process instance using the runtime service when the trigger is unspecified, typically through an API call.

```java
ProcessInstance processInstance = runtimeService.startProcessInstanceByXXX();
```

--------------------------------

### Example User Query for IdmIdentityService

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/zh_CN/bpmn/ch17-Advanced.adoc

This example demonstrates a user query that would be invoked on the IdmIdentityService interface, specifically counting members of a group.

```java
long potentialOwners = identityService.createUserQuery().memberOfGroup("management").count();
```

--------------------------------

### Start CMMN Case Instance with Variables

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/en/cmmn/ch06-cmmn.adoc

Starts a new case instance for a given case definition key and provides initial variables.

```java
CmmnRuntimeService cmmnRuntimeService = cmmnEngine.getCmmnRuntimeService();
CaseInstance caseInstance = cmmnRuntimeService.createCaseInstanceBuilder()
    .caseDefinitionKey("employeeOnboarding")
    .variable("potentialEmployee", "johnDoe")
    .start();
```

--------------------------------

### Start Process Instance by Message (Java)

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/en/bpmn/ch07b-BPMN-Constructs.adoc

Starts a new process instance using a message name. Overloaded methods allow for including process variables and a business key.

```java
ProcessInstance startProcessInstanceByMessage(String messageName);
```

```java
ProcessInstance startProcessInstanceByMessage(String messageName, Map<String, Object> processVariables);
```

```java
ProcessInstance startProcessInstanceByMessage(String messageName, String businessKey,
    Map<String, Object> processVariables);
```

--------------------------------

### Declaratively Start a Process Instance with @StartProcess

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/zh_CN/bpmn/ch15-Cdi.adoc

Use the @StartProcess annotation to declaratively start a process instance by its 'key' or 'name'. The process instance starts after the annotated method returns. This operation is typically part of the same transaction as the method execution.

```java
@StartProcess("authorizeBusinessTripRequest")
public String submitRequest(BusinessTripRequest request) {
	// 进行一些操作
	return "success";
}
```

--------------------------------

### Declarative Process Start with @StartProcess Annotation

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/en/bpmn/ch15-Cdi.adoc

Starts a process instance declaratively using the @StartProcess annotation. The process is started after the annotated method returns, and the process key is specified as an argument to the annotation.

```java
@StartProcess("authorizeBusinessTripRequest")
public String submitRequest(BusinessTripRequest request) {
	// do some work
	return "success";
}
```

--------------------------------

### Attachment Query Examples

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/zh_CN/bpmn/ch17-Advanced.adoc

Demonstrates how to use the AttachmentQuery to retrieve attachments based on various criteria like ID, name, type, and user ID. It also shows how to get the total count and retrieve attachments in pages.

```java
long count = new AttachmentQuery(managementService).count();

Attachment attachment = new AttachmentQuery(managementService).attachmentId("10025").singleResult();

List<Attachment> attachments = new AttachmentQuery(managementService).listPage(0, 10);

attachments = new AttachmentQuery(managementService).userId("kermit").list();
```

--------------------------------

### Start Event with Form Key

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/en/bpmn/ch07b-BPMN-Constructs.adoc

Use the 'formKey' extension in an XML start event to reference a form definition that users must complete when initiating a new process instance.

```xml
<startEvent id="request" flowable:formKey="request" />
```

--------------------------------

### Example flowable.cmmn.cfg.xml Configuration

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/en/cmmn/ch02-Configuration.adoc

An example Spring XML configuration for the CmmnEngineConfiguration, specifying database connection properties and schema update.

```xml
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd">

  <bean id="cmmnEngineConfiguration" class="org.flowable.cmmn.engine.CmmnEngineConfiguration">

    <property name="jdbcUrl" value="jdbc:h2:mem:flowable;DB_CLOSE_DELAY=1000" />
    <property name="jdbcDriver" value="org.h2.Driver" />
    <property name="jdbcUsername" value="sa" />
    <property name="jdbcPassword" value="" />

    <property name="databaseSchemaUpdate" value="true" />
  </bean>

</beans>
```

--------------------------------

### Java Delegate to Start Process Instance

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/en/bpmn/ch07b-BPMN-Constructs.adoc

A Java delegate that uses the RuntimeService to start a new process instance by its key. This is useful when callActivity is not suitable.

```java
public class StartProcessInstanceTestDelegate implements JavaDelegate {

  public void execute(DelegateExecution execution) throws Exception {
    RuntimeService runtimeService = Context.getProcessEngineConfiguration().getRuntimeService();
    runtimeService.startProcessInstanceByKey("myProcess");
  }

}
```

--------------------------------

### Start Process Instance with JPA Entity Variable

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/en/bpmn/ch09-JPA.adoc

Starts a process instance and adds a JPA entity as a process variable. The entity will be persisted by the engine.

```java
Map<String, Object> variables = new HashMap<String, Object>();
variables.put("entityToUpdate", entityToUpdate);

ProcessInstance processInstance = runtimeService.startProcessInstanceByKey(
    "UpdateJPAValuesProcess", variables);
```

--------------------------------

### Get Start Form Data

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/en/bpmn/ch08-Forms.adoc

Retrieves form properties for the start event of a process definition. This can be empty if no specific mapping is defined.

```java
formService.getStartFormData(String processDefinitionId).getFormProperties()
```

--------------------------------

### Get Start Form Data

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/en/bpmn/ch08-Forms.adoc

Retrieves the start form data for a process definition. This exposes property information for UI form building.

```java
StartFormData FormService.getStartFormData(String processDefinitionId)
```

--------------------------------

### Starting a Process Instance with Transient Variables

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/zh_CN/bpmn/ch04-API.adoc

Demonstrates how to start a new process instance and set initial transient variables using the ProcessInstanceBuilder. These variables are useful for passing configuration or temporary data to the initial steps of a process.

```java
ProcessInstance processInstance = runtimeService.createProcessInstanceBuilder()
       .processDefinitionKey("someKey")
       .transientVariable("configParam01", "A")
       .transientVariable("configParam02", "B")
       .transientVariable("configParam03", "C")
       .start();
```

--------------------------------

### Java Code for Starting a Process Instance and Querying Tasks

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/zh_CN/bpmn/ch07b-BPMN-Constructs.adoc

This Java code demonstrates how to start a process instance by key and query for tasks associated with that instance. It includes setting process variables and asserting the number and name of the retrieved tasks.

```java
HashMap<String, Object> variableMap = new HashMap<String, Object>();
variableMap.put("receivedPayment", true);
variableMap.put("shipOrder", true);

ProcessInstance pi = runtimeService.startProcessInstanceByKey("forkJoin");

TaskQuery query = taskService.createTaskQuery()
    .processInstanceId(pi.getId())
    .orderByTaskName()
    .asc();

List<Task> tasks = query.list();
assertEquals(1, tasks.size());

Task task = tasks.get(0);
assertEquals("Ship Order", task.getName());
```

--------------------------------

### Getting Form Data

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/zh_CN/bpmn/ch08-Forms.adoc

Retrieve form data for starting a process or completing a task.

```APIDOC
## Get Start Form Data

### Description
Retrieves the start form data for a given process definition.

### Method
`FormService.getStartFormData(String processDefinitionId)`

## Get Task Form Data

### Description
Retrieves the task form data for a given task.

### Method
`FormService.getTaskFormData(String taskId)`
```

--------------------------------

### Define Start Event Form Properties with Types and Values

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/en/bpmn/ch08-Forms.adoc

Example of defining form properties for a start event in BPMN XML, specifying types, display names, and enum values.

```xml
<startEvent id="start">
  <extensionElements>
    <flowable:formProperty id="speaker"
      name="Speaker"
      variable="SpeakerName"
      type="string" />

    <flowable:formProperty id="start"
      type="date"
      datePattern="dd-MMM-yyyy" />

    <flowable:formProperty id="direction" type="enum">
      <flowable:value id="left" name="Go Left" />
      <flowable:value id="right" name="Go Right" />
      <flowable:value id="up" name="Go Up" />
      <flowable:value id="down" name="Go Down" />
    </flowable:formProperty>

  </extensionElements>
</startEvent>
```

--------------------------------

### Event Sub-Process with Error Start Event

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/zh_CN/bpmn/ch07b-BPMN-Constructs.adoc

Example of an event sub-process triggered by an error start event at the process level. This sub-process handles errors within the scope of the entire process instance.

```xml
<subProcess id="eventSubProcess" triggeredByEvent="true">
    <startEvent id="catchError">
        <errorEventDefinition errorRef="error" />
    </startEvent>
    <sequenceFlow id="flow2" sourceRef="catchError" targetRef="taskAfterErrorCatch" />
    <userTask id="taskAfterErrorCatch" name="Provide additional data" />
</subProcess>
```

--------------------------------

### Start Process Instance Request Body (by Process Definition Key)

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/zh_CN/bpmn/ch14-REST.adoc

JSON payload to start a new process instance using its definition key. Includes optional business key, tenant ID, return variables flag, and variables.

```json
{
   "processDefinitionKey":"oneTaskProcess",
   "businessKey":"myBusinessKey",
   "returnVariables":false,
   "tenantId": "tenant1",
   "variables": [
      {
        "name":"myVar",
        "value":"This is a variable",
      }
   ]
}
```

--------------------------------

### Define Potential Starters using Attributes

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/zh_CN/bpmn/ch07b-BPMN-Constructs.adoc

Define users and groups allowed to start process instances using the flowable:candidateStarterUsers and flowable:candidateStarterGroups attributes on the process element.

```xml
<process id="potentialStarter" flowable:candidateStarterUsers="user1, user2"
    flowable:candidateStarterGroups="group1">
    ...
</process>
```

--------------------------------

### Get Process Instance Success Response Body

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/zh_CN/bpmn/ch14-REST.adoc

Example JSON response when a process instance is successfully retrieved.

```json
{
   "id":"7",
   "url":"http://localhost:8182/runtime/process-instances/7",
   "businessKey":"myBusinessKey",
   "suspended":false,
   "processDefinitionUrl":"http://localhost:8182/repository/process-definitions/processOne%3A1%3A4",
   "activityId":"processTask",
   "tenantId": null
}
```

--------------------------------

### Getting Form Models

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/zh_CN/bpmn/ch08-Forms.adoc

Retrieve form models for starting a process or completing a task using the Flowable API.

```APIDOC
## Get Start Form Model

### Description
Retrieves the form model for starting a process instance.

### Method
`RuntimeService.getStartFormModel(String processDefinitionId, String processInstanceId)`

## Get Task Form Model

### Description
Retrieves the form model for completing a user task.

### Method
`TaskService.getTaskFormModel(String taskId)`
```

--------------------------------

### Start a Process Instance with Variables

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/en/bpmn/ch02-GettingStarted.adoc

Start a process instance using the RuntimeService by providing a process key and a map of initial process variables. The process key must match the 'id' attribute in the BPMN 2.0 XML file.

```java
RuntimeService runtimeService = processEngine.getRuntimeService();

Map<String, Object> variables = new HashMap<String, Object>();
variables.put("employee", employee);
variables.put("nrOfHolidays", nrOfHolidays);
variables.put("description", description);
ProcessInstance processInstance = 
  runtimeService.startProcessInstanceByKey("holidayRequest", variables);
```

--------------------------------

### Get Single Group - Response Body

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/zh_CN/bpmn/ch14-REST.adoc

Example JSON response body for a successful request to retrieve a single group.

```json
{
   "id":"testgroup",
   "url":"http://localhost:8182/identity/groups/testgroup",
   "name":"Test group",
   "type":"Test type"
}
```

--------------------------------

### StandaloneProcessEngineConfiguration Example

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/zh_CN/bpmn/ch03-Configuration.adoc

Basic configuration for a standalone Flowable process engine, specifying the data source.

```xml
<bean id="processEngineConfiguration" class="org.flowable.engine.impl.cfg.StandaloneProcessEngineConfiguration">

  <property name="dataSource" ref="dataSource" />
  ...

```

--------------------------------

### cURL Commands for REST API Interaction

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/en/bpmn/ch05a-Spring-Boot.adoc

Examples of using cURL to interact with the Flowable REST API endpoints for fetching tasks and starting processes.

```bash
curl http://localhost:8080/tasks?assignee=kermit
[]

curl -X POST  http://localhost:8080/process
curl http://localhost:8080/tasks?assignee=kermit
[{"id":"10004","name":"my task"}]
```

--------------------------------

### Form Rendering and Submission APIs

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/zh_CN/bpmn/ch08-Forms.adoc

Details on how to get form data for starting a process or completing a task, and how to submit this data back to the Flowable engine.

```APIDOC
## Form Rendering and Submission

### Description

Flowable provides APIs to render task forms externally and to submit form data. The `FormService` offers methods to retrieve form data and submit user input.

### API Methods

- **Get Form Data:**
  - `StartFormData FormService.getStartFormData(String processDefinitionId)`: Retrieves form data for starting a process.
  - `TaskFormData FormService.getTaskFormData(String taskId)`: Retrieves form data for a task.

- **Submit Form Data:**
  - `ProcessInstance FormService.submitStartFormData(String processDefinitionId, Map<String,String> properties)`: Submits form data for starting a process.
  - `void FormService.submitTaskFormData(String taskId, Map<String,String> properties)`: Submits form data for a task.

### Related Concepts

- Refer to <<formProperties>> for mapping form parameters to process variables.
```

--------------------------------

### Starting a Process Instance by Key in Flowable

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/en/bpmn/ch07a-BPMN-Introduction.adoc

Demonstrates how to initiate a new process instance using the 'startProcessInstanceByKey' method from the Flowable RuntimeService. This method uses the process definition's 'id' attribute.

```java
ProcessInstance processInstance = runtimeService.startProcessInstanceByKey("myProcess");
```

--------------------------------

### Get List of Groups - Response Body

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/zh_CN/bpmn/ch14-REST.adoc

Example JSON response body for a successful request to retrieve a list of groups, including pagination and sorting details.

```json
{
   "data":[
     {
        "id":"testgroup",
        "url":"http://localhost:8182/identity/groups/testgroup",
        "name":"Test group",
        "type":"Test type"
     }
   ],
   "total":3,
   "start":0,
   "sort":"id",
   "order":"asc",
   "size":3
}
```

--------------------------------

### Get a Process Definition - HTTP Request Example

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/zh_CN/bpmn/ch14-REST.adoc

This is the HTTP method and endpoint for retrieving a specific process definition by its ID. The processDefinitionId is a required path parameter.

```http
GET repository/process-definitions/{processDefinitionId}
```

--------------------------------

### Starting a Process with a Form

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/zh_CN/bpmn/ch08-Forms.adoc

Initiate a process instance using a form definition and provided variables.

```APIDOC
## Start Process Instance with Form

### Description
Starts a process instance using a form definition and submitting values from the form.

### Method
`RuntimeService.startProcessInstanceWithForm(String processDefinitionId, String outcome, Map<String, Object> variables, String processInstanceName)`

### Parameters
* `processDefinitionId` (String) - The ID of the process definition.
* `outcome` (String) - The outcome of the form submission.
* `variables` (Map<String, Object>) - A map of variables to be set for the process instance.
* `processInstanceName` (String) - The name for the new process instance.
```

--------------------------------

### Query Historic Details - Success Response Body

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/en/bpmn/ch14-REST.adoc

Example JSON response body for a successful historic detail query. The structure is similar to the GET response.

```json
{
  "data": [
    {
      "id" : "26",
      "processInstanceId" : "5",
      "processInstanceUrl" : "http://localhost:8182/history/historic-process-instances/5",
      "executionId" : "6",
      "activityInstanceId", "10",
      "taskId" : "6",
      "taskUrl" : "http://localhost:8182/history/historic-task-instances/6",
      "time" : "2013-04-17T10:17:43.902+0000",
      "detailType" : "variableUpdate",
      "revision" : 2,
      "variable" : {
        "name" : "myVariable",
        "variableScope", "global",
        "value" : "test"
      },
      "propertyId" : null,
      "propertyValue" : null
    }
  ],
  "total": 1,
  "start": 0,
  "sort": "name",
  "order": "asc",
  "size": 1
}
```

--------------------------------

### Start Process Instance Request Body (by Message)

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/zh_CN/bpmn/ch14-REST.adoc

JSON payload to start a new process instance by sending a message. Includes optional business key, tenant ID, and variables.

```json
{
   "message":"newOrderMessage",
   "businessKey":"myBusinessKey",
   "tenantId": "tenant1",
   "variables": [
      {
        "name":"myVar",
        "value":"This is a variable",
      }
   ]
}
```

--------------------------------

### Get Historic Detail - Success Response Body

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/en/bpmn/ch14-REST.adoc

Example JSON response body for a successful historic detail retrieval. It includes details about the variable update.

```json
{
  "data": [
    {
      "id" : "26",
      "processInstanceId" : "5",
      "processInstanceUrl" : "http://localhost:8182/history/historic-process-instances/5",
      "executionId" : "6",
      "activityInstanceId", "10",
      "taskId" : "6",
      "taskUrl" : "http://localhost:8182/history/historic-task-instances/6",
      "time" : "2013-04-17T10:17:43.902+0000",
      "detailType" : "variableUpdate",
      "revision" : 2,
      "variable" : {
        "name" : "myVariable",
        "variableScope", "global",
        "value" : "test"
      },
      "propertyId": null,
      "propertyValue": null
    }
  ],
  "total": 1,
  "start": 0,
  "sort": "name",
  "order": "asc",
  "size": 1
}
```

--------------------------------

### Start Enabled Plan Item Instance

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/zh_CN/cmmn/ch06-cmmn.adoc

Use this method to start a plan item instance that is in the ENABLED state. This moves the plan item instance to the ACTIVE state, triggering its behavior.

```java
List<PlanItemInstance> enabledPlanItemInstances = cmmnRuntimeService.createPlanItemInstanceQuery()
    .caseInstanceId(caseInstance.getId())
    .planItemInstanceStateEnabled()
    .list();
    
// ...
    
cmmnRuntimeService.startPlanItemInstance(planItemInstance.getId());
```

--------------------------------

### Get Form Instance Success Response

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/en/form/ch07-REST.adoc

Example of a successful response when retrieving a form instance. This JSON object represents the details of a stored form instance.

```json
{
   "id":"48b9ac82-f1d3-11e6-8549-acde48001122",
   "url":"http://localhost:8182/form/form-instances/48b9ac82-f1d3-11e6-8549-acde48001122",
   "formDefinitionId":"818e4703-f1d2-11e6-8549-acde48001122",
   "taskId":"88",
   "processInstanceId":"66",
   "processDefinitionId":"oneTaskProcess:1:158",
   "submittedDate":"2013-04-17T10:17:43.902+0000",
   "submittedBy":"testUser",
   "formValuesId":"818e4703-f1d2-11e6-8549-acde48001110",
   "tenantId": null
}
```

--------------------------------

### Define Candidate Starters using Attributes

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/en/bpmn/ch07b-BPMN-Constructs.adoc

This XML snippet shows an alternative way to define users and groups allowed to initiate a process instance by using the 'flowable:candidateStarterUsers' and 'flowable:candidateStarterGroups' attributes on the <process> tag.

```xml
<process id="potentialStarter" flowable:candidateStarterUsers="user1, user2"
    flowable:candidateStarterGroups="group1">
    ...

```

--------------------------------

### Define Potential Starters for a Process

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/en/bpmn/ch07b-BPMN-Constructs.adoc

This XML snippet demonstrates how to define specific users and groups that are allowed to initiate a process instance using the <flowable:potentialStarter> tag.

```xml
<process id="potentialStarter">
  <extensionElements>
    <flowable:potentialStarter>
       <resourceAssignmentExpression>
         <formalExpression>group2, group(group3), user(user3)</formalExpression>
       </resourceAssignmentExpression>
    </flowable:potentialStarter>
  </extensionElements>

  <startEvent id="theStart"/>
  ...

```

--------------------------------

### Get a single user - Success Response Body

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/en/bpmn/ch14-REST.adoc

Example JSON response when successfully retrieving a single user. This shows the structure of user data returned by the API.

```json
{
   "id":"testuser",
   "firstName":"Fred",
   "lastName":"McDonald",
   "url":"http://localhost:8182/identity/users/testuser",
   "email":"no-reply@flowable.org"
}
```

--------------------------------

### Get a list of jobs - Success Response Body

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/en/bpmn/ch14-REST.adoc

Example of a successful response when retrieving a list of jobs. It includes job details, total count, and pagination information.

```json
{
   "data":[
      {
         "id":"13",
         "url":"http://localhost:8182/management/jobs/13",
         "processInstanceId":"5",
         "processInstanceUrl":"http://localhost:8182/runtime/process-instances/5",
         "processDefinitionId":"timerProcess:1:4",
         "processDefinitionUrl":"http://localhost:8182/repository/process-definitions/timerProcess%3A1%3A4",
         "executionId":"12",
         "executionUrl":"http://localhost:8182/runtime/executions/12",
         "retries":0,
         "exceptionMessage":"Can't find scripting engine for 'unexistinglanguage'",
         "dueDate":"2013-06-07T10:00:24.653+0000",
         "tenantId":null
      }


   ],
   "total":2,
   "start":0,
   "sort":"id",
   "order":"asc",
   "size":2
}
```

--------------------------------

### Create Basic Java Class with Main Method

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/en/bpmn/ch02-GettingStarted.adoc

Set up a new Java class with a main method to serve as the entry point for your Flowable application. This is where you will initialize the process engine and interact with Flowable APIs.

```java
package org.flowable;

public class HolidayRequest {

  public static void main(String[] args) {

  }

}
```

--------------------------------

### Get Execution Variable Response Body

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/en/bpmn/ch14-REST.adoc

Example JSON response body when successfully retrieving a variable from an execution. The 'valueUrl' field is present for binary or serializable variables.

```json
   {
      "name":"intProcVar",
      "type":"integer",
      "value":123,
      "scope":"local"
   }
```

--------------------------------

### Start Process Instance with Variables

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/zh_CN/bpmn/ch04-API.adoc

Set process variables during the creation and initiation of a process instance using the RuntimeService.

```java
ProcessInstance startProcessInstanceByKey(String processDefinitionKey, Map<String, Object> variables);
```

--------------------------------

### Spring Boot CommandLineRunner for Initialization

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/zh_CN/bpmn/ch05a-Spring-Boot.adoc

Use CommandLineRunner to execute initialization logic when a Spring Boot application starts. This example shows how to create demo users via MyService.

```java
@Bean
public CommandLineRunner init(final MyService myService) {

    return new CommandLineRunner() {
    	public void run(String... strings) throws Exception {
        	myService.createDemoUsers();
        }
    };
}
```

--------------------------------

### REST Controller for Flowable Process Interaction

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/en/bpmn/ch05a-Spring-Boot.adoc

Create a REST controller to expose Flowable process management functionalities. This example includes endpoints for starting a process and fetching tasks.

```java
@RestController
public class MyRestController {

    @Autowired
    private MyService myService;

    @RequestMapping(value="/process", method= RequestMethod.POST)
    public void startProcessInstance() {
        myService.startProcess();
    }

    @RequestMapping(value="/tasks", method= RequestMethod.GET, produces=MediaType.APPLICATION_JSON_VALUE)
    public List<TaskRepresentation> getTasks(@RequestParam String assignee) {
        List<Task> tasks = myService.getTasks(assignee);
        List<TaskRepresentation> dtos = new ArrayList<TaskRepresentation>();
        for (Task task : tasks) {
            dtos.add(new TaskRepresentation(task.getId(), task.getName()));
        }
        return dtos;
    }

    static class TaskRepresentation {

        private String id;
        private String name;

        public TaskRepresentation(String id, String name) {
            this.id = id;
            this.name = name;
        }
        
        public String getId() {
            return id;
        }
        public void setId(String id) {
            this.id = id;
        }
        public String getName() {
            return name;
        }
        public void setName(String name) {
            this.name = name;
        }

    }

}
```

--------------------------------

### Start Process Instance Request Body (by Process Definition ID)

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/zh_CN/bpmn/ch14-REST.adoc

JSON payload to start a new process instance using its definition ID. Includes optional business key, return variables flag, and variables.

```json
{
   "processDefinitionId":"oneTaskProcess:1:158",
   "businessKey":"myBusinessKey",
   "returnVariables":true,
   "variables": [
      {
        "name":"myVar",
        "value":"This is a variable",
      }
   ]
}
```

--------------------------------

### Get Groups Authorized to Start a Process Definition

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/zh_CN/bpmn/ch07b-BPMN-Constructs.adoc

Query for groups that are configured as potential starters for a specific process definition using the identityService. This is useful for managing group-based permissions.

```java
List<Group> authorizedGroups = identityService().createGroupQuery()
    .potentialStarter("processDefinitionId")
    .list();
```

--------------------------------

### Build ProcessEngine with Programmatic Configuration

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/en/bpmn/ch03-Configuration.adoc

Build a ProcessEngine instance by programmatically setting configuration properties.

```java
ProcessEngine processEngine = ProcessEngineConfiguration.createStandaloneInMemProcessEngineConfiguration()
  .setDatabaseSchemaUpdate(ProcessEngineConfiguration.DB_SCHEMA_UPDATE_FALSE)
  .setJdbcUrl("jdbc:h2:mem:my-own-db;DB_CLOSE_DELAY=1000")
  .setAsyncExecutorActivate(false)
  .buildProcessEngine();
```

--------------------------------

### Get a list of users - Success Response Body

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/en/bpmn/ch14-REST.adoc

Example JSON response when successfully retrieving a list of users. It includes an array of user objects, total count, and pagination details.

```json
{
   "data":[
      {
         "id":"anotherUser",
         "firstName":"Tijs",
         "lastName":"Barrez",
         "url":"http://localhost:8182/identity/users/anotherUser",
         "email":"no-reply@flowable.org"
      },
      {
         "id":"kermit",
         "firstName":"Kermit",
         "lastName":"the Frog",
         "url":"http://localhost:8182/identity/users/kermit",
         "email":null
      },
      {
         "id":"testuser",
         "firstName":"Fred",
         "lastName":"McDonald",
         "url":"http://localhost:8182/identity/users/testuser",
         "email":"no-reply@flowable.org"
      }
   ],
   "total":3,
   "start":0,
   "sort":"id",
   "order":"asc",
   "size":3
}
```

--------------------------------

### RuntimeService

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/zh_CN/bpmn/ch04-API.adoc

Start new process instances, manage process variables, and query process instances and executions.

```APIDOC
## RuntimeService

### Description
The `RuntimeService` is used to start new process instances of process definitions. It also handles reading and storing process variables, which are data used throughout a process instance. Additionally, it allows querying for process instances and executions (tokens).

### Key Operations
- Start new process instances.
- Read and store process variables.
- Query process instances and executions.
- Signal waiting process instances to continue execution.
```

--------------------------------

### Spring Integration Unit Test Setup

Source: https://github.com/tkjohn/flowable-userguide/blob/master/src/zh_CN/bpmn/ch05-Spring.adoc

Example of setting up a JUnit 4 test class for Flowable processes integrated with Spring. It uses SpringJUnit4ClassRunner and injects necessary Flowable services.

```java
@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration("classpath:org/flowable/spring/test/junit4/springTypicalUsageTest-context.xml")
public class MyBusinessProcessTest {

  @Autowired
  private RuntimeService runtimeService;

  @Autowired
  private TaskService taskService;

  @Autowired
  @Rule
  public FlowableRule flowableSpringRule;
}
```