### Classic API Example: Manually Start Case Execution

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/reference/cmmn11/classic-vs-fluent.md

Demonstrates how to manually start a case execution using the classic API, with and without variables.

```APIDOC
## Classic API Example: Manually Start Case Execution

### Description
Manually starts a case execution using the classic API.

### Method
```java
caseService.manuallyStartCaseExecution(caseExecutionId);

Map<String, Object> variables = new HashMap<String, Object>();
variables.put("aVariableToSet", "aValueToSet");

caseService.manuallyStartCaseExecution(caseExecutionId, variables);
```
```

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

### Enable Example Application

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/operaton-bpm-run.md

Set 'operaton.bpm.run.example.enabled' to true to enable the demo application. This application deploys resources and starts process instances.

```yaml
operaton.bpm.run.example.enabled: true
```

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

### Fluent API Example: Manually Start Case Execution

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/reference/cmmn11/classic-vs-fluent.md

Demonstrates how to manually start a case execution using the fluent API, with and without variables.

```APIDOC
## Fluent API Example: Manually Start Case Execution

### Description
Manually starts a case execution using the fluent API.

### Method
```java
caseService
  .withCaseExecution(caseExecutionId)
  .manualStart();

Map<String, Object> variables = new HashMap<String, Object>();
variables.put("aVariableToSet", "aValueToSet");

caseService
  .withCaseExecution(caseExecutionId)
  .setVariables(variables)
  .manualStart();
```
```

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

### Example: Create a Simple Process with One User Task

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/model-api/bpmn-model-api/create-a-model.md

Creates a BPMN model with a start event, a user task, and an end event, connected by sequence flows. This example uses the helper methods for element and sequence flow creation.

```java
// create an empty model
BpmnModelInstance modelInstance = Bpmn.createEmptyModel();
Definitions definitions = modelInstance.newInstance(Definitions.class);
definitions.setTargetNamespace("http://operaton.org/examples");
modelInstance.setDefinitions(definitions);

// create the process
Process process = createElement(definitions, "process-with-one-task", Process.class);

// create start event, user task and end event
StartEvent startEvent = createElement(process, "start", StartEvent.class);
UserTask task1 = createElement(process, "task1", UserTask.class);
task1.setName("User Task");
EndEvent endEvent = createElement(process, "end", EndEvent.class);

// create the connections between the elements
createSequenceFlow(process, startEvent, task1);
createSequenceFlow(process, task1, endEvent);

// validate and write model to file
Bpmn.validateModel(modelInstance);
File file = File.createTempFile("bpmn-model-api-", ".bpmn");
Bpmn.writeModelToFile(file, modelInstance);
```

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

### Start Process Instance by Latest Version Tag

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/process-engine/process-versioning.md

Start a process instance using the latest process definition that matches a specific key and version tag. Ensure the query is ordered by version descending and paginated to get the latest.

```java
ProcessDefinition pd = processEngine.getRepositoryService().createProcessDefinitionQuery()
    .processDefinitionKey("invoice")
    .versionTag("1.5-patch2")
    .orderByVersion().
    .desc() 
    .listPage(0,1);

processEngine.getRuntimeService().startProcessInstanceById(pd.getId());
```

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

### Java API for Inclusive Gateway Fork

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/reference/bpmn20/gateways/inclusive-gateway.md

Demonstrates starting a process instance with specific variables and asserting the resulting tasks. This example shows how to programmatically control the conditions evaluated by an inclusive gateway.

```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());
```

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

### Start Local Development Server

Source: https://github.com/operaton/documentation/blob/main/README.md

Starts a local development server for Operaton documentation. Changes are reflected without restarting.

```bash
npm run start
```

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

### Start a Process Instance by Key

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/process-engine/process-engine-concepts.md

Initiates a new process instance using its business key. This is the most common way to start a process.

```java
ProcessInstance instance = runtimeService.startProcessInstanceByKey("invoice");
```

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

### Restrict Process Instance Creation Authorization

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/process-engine/authorization-service.md

This example demonstrates how to set up two authorizations: one to control access to a process definition and another to allow the creation of process instances. This is useful for restricting who can start specific processes.

```java
//we need to authorizations, one to access the process definition and another one to create process instances
Authorization authProcessDefinition = authorizationService.createNewAuthorization(AUTH_TYPE_GRANT);
Authorization authProcessInstance = authorizationService.createNewAuthorization(AUTH_TYPE_GRANT);

authProcessDefinition.setUserId("johnny");
authProcessInstance.setUserId("johnny");

authProcessDefinition.setResource(Resources.PROCESS_DEFINITION);
authProcessInstance.setResource(Resources.PROCESS_INSTANCE);
//the resource id for a process definition is the process definition key
authProcessDefinition.setResourceId("invoice");
//asterisk to allow the start of a process instance
authProcessInstance.setResourceId("*")
// allow the user to create instances of this process definition
authProcessDefinition.addPermission(Permissions.CREATE_INSTANCE);
// and to create processes
authProcessInstance.addPermission(Permissions.CREATE);

authorizationService.saveAuthorization(authProcessDefinition);
authorizationService.saveAuthorization(authProcessInstance);
```

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

### Resource Example

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/reference/rest/overview/hal.md

Example of fetching a single resource using the HAL media type.

```APIDOC
## GET /task/{taskId}

### Description
Fetches a specific task resource using the HAL media type, embedding related resources like assignee and process definition.

### Method
GET

### Endpoint
/task/{taskId}

### Request Header
```
Accept: application/hal+json
```

### Response
#### Success Response (200)
```json
{
  "_links" : {
    "self": {
      "href": "/task/a-task-id"
    },
    "assignee": {
      "href": "/user/demo"
    },
    ...
  },
  "_embedded" : {
    "group" : [{
      "_links" : {
        "self" : {
          "href" : "/group/management"
        }
      },
      "_embedded" : null,
      "id" : "management",
      ...
    }],
    "processDefinition" : [ {...}, {...} ],
    ...
  },
  "id" : "a-task-id",
  "name": "Assign Approver",
  "assignee": "demo",
  ...
}
```
```

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

### Start Process Instance on Post Deploy Event

Source: https://github.com/operaton/documentation/blob/main/docs/get-started/spring-boot/model.md

Listen for the PostDeployEvent to automatically start a process instance by its key. Requires the RuntimeService to be injected.

```java
...
  @Autowired
  private RuntimeService runtimeService;

  @EventListener
  private void processPostDeploy(PostDeployEvent event) {
    runtimeService.startProcessInstanceByKey("loanApproval");
  }
...
```

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

### Start Process Instance by Key

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/reference/bpmn20/events/none-events.md

Use this method to start a process instance when the trigger is unspecified. This is common for processes started via API.

```java
ProcessInstance processInstance = runtimeService.startProcessInstanceByKey('invoice');
```

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

### Start a Process Instance with Variables

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/process-engine/process-engine-concepts.md

Starts a process instance and provides initial variables. These variables are persisted if the process reaches a wait state.

```java
Map<String, Object> variables = new HashMap<String,Object>();
variables.put("creditor", "Nice Pizza Inc.");
ProcessInstance instance = runtimeService.startProcessInstanceByKey("invoice", variables);
```

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

### Start Latest Process Instance by Key

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/process-engine/process-versioning.md

Starts a new process instance using the latest deployed version of the specified process definition key. This is the default and recommended approach.

```java
processEngine.getRuntimeService().startProcessInstanceByKey("invoice");
// will use the latest version (2 in our example)
```

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

### Custom Properties File Example

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/ext-client/spring-boot-starter.md

Example content for a client.properties file used for resolving string-based properties.

```properties
client.baseUrl=http://localhost:8080/engine-rest
client.workerId=spring-boot-worker
client.dateFormat=yyyy-MM-dd'T'HH:mm:ss.SSSZ
client.serializationFormat=application/json
```

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

### Create Start Form Instance

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/reference/forms/embedded-forms/integrate/bootstrapping.md

Initialize a CamSDK.Form instance for a start form by providing the client and a process definition ID. This configuration is used when form submission should start a new process instance.

```javascript
new CamSDK.Form({
  client: camClient,

  // the process definition ID
  processDefinitionId: 'someProcessDefinitionId',

  //...
});
```

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

### Install Operaton External Task Client and Open

Source: https://github.com/operaton/documentation/blob/main/docs/get-started/quick-start/service-task.md

Installs the necessary npm packages for the Operaton external task client and the 'open' utility for development dependencies.

```sh
npm install operaton-external-task-client-js
npm install -D open
```

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

### Start Case Execution Manually (Classic API)

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/reference/cmmn11/classic-vs-fluent.md

Use the classic API to manually start a case execution. Variables can be provided during the start.

```java
caseService.manuallyStartCaseExecution(caseExecutionId);

Map<String, Object> variables = new HashMap<String, Object>();
variables.put("aVariableToSet", "aValueToSet");

caseService.manuallyStartCaseExecution(caseExecutionId, variables);
```

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

### Start New Activity and Cancel Activity (Start First)

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/process-engine/process-instance-modification.md

Use this snippet to first start a new activity before a target activity and then cancel all instances of a specific activity. Starting first preserves the existing process instance and its associated entities.

```java
ProcessInstance processInstance = ...;
runtimeService.createProcessInstanceModification(processInstance.getId())
  .startBeforeActivity("registerApplication")
  .cancelAllForActivity("assesCreditWorthiness")
  .execute();
```

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

### Manually Starting a Decision Task

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/reference/cmmn11/tasks/decision-task.md

Demonstrates how to manually start a case execution that includes a decision task using the CaseService.

```java
caseService.manuallyStartCaseExecution("aCaseExecutionId");
```

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

### Install Forms SDK with Bower

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/reference/forms/embedded-forms/integrate/getting-a-distribution.md

Use this command to install the Forms SDK using the Bower package manager. Ensure Bower is installed and configured in your project.

```bash
bower install operaton-bpm-sdk-js --save
```

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

### Start Process Instance Declaratively

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/cdi-java-ee-integration/contextual-programming-model.md

Use the @StartProcess annotation to start a process instance after the annotated method returns. The process instance is started by its key.

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

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

### Collection Example

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/reference/rest/overview/hal.md

Example of fetching a collection of resources using the HAL media type.

```APIDOC
## GET /task

### Description
Fetches a collection of task resources using the HAL media type, embedding related resources like assignees and process definitions.

### Method
GET

### Endpoint
/task

### Request Header
```
Accept: application/hal+json
```

### Response
#### Success Response (200)
```json
{
  "_links" : {
    "self": {
      "href": "/task"
    }
  },
  "_embedded" : {
    "assignee" : [{
      "_links" : {
        "self" : {
          "href" : "/user/demo"
        }
      },
      "_embedded" : null,
      "id": "demo",
      ...
    }],
    "processDefinition" : [ {...} ],
    "task" : [{
      "_links" : {
        "self": {
          "href": "/task/a-task-id"
        },
        "assignee": {
          "href": "/user/demo"
        },
        ...
      },
      "_embedded" : {
        "variable" : [ {...}, {...} ]
      },
      "id" : "a-task-id",
      "name": "Assign Approver",
      "assignee": "demo",
      ...
    }, {
      ...
    }]
  },
  "count" : 2
}
```
```

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

### Start Process Instance with Signal

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/reference/bpmn20/events/signal-events.md

Use these methods on the RuntimeService to trigger a process instance start event based on a signal name. A single signal can start multiple process instances if multiple definitions have a matching signal start event.

```java
void signalEventReceived(String signalName);
void signalEventReceived(String signalName, Map<String, Object> processVariables);
```

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

### Example JSON Structure

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/data-formats/json.md

Illustrates the structure of a customer JSON object used in subsequent examples.

```json
{
  "name" : "jonny",
  "address" : {
    "street" : "12 High Street",
    "post code" : 1234
  }
}
```

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

### Create a Simple GET Request

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/reference/connect/http-connector.md

How to create and execute a basic HTTP GET request.

```APIDOC
## Create a Simple GET Request

```java
http.createRequest()
  .get()
  .url("http://operaton.org")
  .execute();
```

This example demonstrates creating an HTTP GET request to a specified URL using the `http` connector instance.
```

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

### Start Before an Activity

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/process-engine/process-instance-modification.md

Use to start execution before entering a specified activity. Respects the 'asyncBefore' flag. Continues until a wait state is reached.

```java
ProcessInstanceModificationBuilder#startBeforeActivity(String activityId)
ProcessInstanceModificationBuilder#startBeforeActivity(String activityId, String ancestorActivityInstanceId)
```

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

### JSF Form for Starting a New Process Instance

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/task-forms/jsf-task-forms.md

This snippet provides a complete JSF page structure for starting a new process instance. It includes the necessary JSF and HTML tags, metadata for triggering the process start, and a form to input process variables. The `camundaTaskForm.startProcessInstanceByKeyForm()` method is invoked before the view is rendered.

```xml
<!DOCTYPE HTML>
<html lang="en" xmlns="http://www.w3.org/1999/xhtml"
  xmlns:ui="http://java.sun.com/jsf/facelets"
  xmlns:h="http://java.sun.com/jsf/html"
  xmlns:f="http://java.sun.com/jsf/core">

<f:view>
  <f:metadata>
    <f:event type="preRenderView" listener="#{camundaTaskForm.startProcessInstanceByKeyForm()}" />
  </f:metadata>
  <h:head>
    <title>Start Process: #{camundaTaskForm.processDefinition.name}</title>
  </h:head>
  <h:body>
    <h1>#{camundaTaskForm.processDefinition.name}</h1>
    <p>Start a new process instance in version: #{camundaTaskForm.processDefinition.version}</p>
    <h:form id="someForm">
      <p>
        Here you see the actual form to start a new process instance, normally
        this would be in some design  either matching you task list or your business
        application (or both in the best case).
      </p>

      <table>
        <tr>
          <td>
            Process variable <strong>x</strong>:
          </td>
          <td>
            <h:inputText value="#{processVariables['x']}" />
          </td>
        </tr>
        <tr>
          <td></td>
          <td>
            <h:commandButton id="start" value="Start Process Instance"
                action="#{camundaTaskForm.completeProcessInstanceForm()}" />
          </td>
        </tr>
      </table>
    </h:form>
  </h:body>
</f:view>
</html>
```

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

### Example processes.xml Configuration

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/reference/deployment-descriptors/processes-xml.md

This example shows a basic processes.xml file configuring a process archive named 'loan-approval' to use the default process engine and enabling scanning for process definitions.

```xml
<process-application
  xmlns="http://www.operaton.org/schema/1.0/ProcessApplication"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  <process-archive name="loan-approval">
    <process-engine>default</process-engine>
    <properties>
      <property name="isDeleteUponUndeploy">false</property>
      <property name="isScanForProcessDefinitions">true</property>
    </properties>
  </process-archive>

</process-application>
```

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

### Event Subprocess with Error Start Event

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/reference/bpmn20/subprocesses/event-subprocess.md

An example of an event subprocess triggered by an Error Start Event. This subprocess is scoped to the 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 Before Activity with Variables

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/process-engine/process-engine-concepts.md

Uses a fluent builder to start a process instance before a specific activity and set variables. Multiple `startBeforeActivity` and `setVariable` calls can be chained.

```java
ProcessInstance instance = runtimeService.createProcessInstanceByKey("invoice")
  .startBeforeActivity("SendInvoiceReceiptTask")
  .setVariable("creditor", "Nice Pizza Inc.")
  .startBeforeActivity("DeliverPizzaSubProcess")
  .setVariableLocal("destination", "12 High Street")
  .execute();
```

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

### Get DMN Model and Resources

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/process-engine/decisions/repository.md

Examples of retrieving the DMN model instance, DMN XML input stream, and decision diagram input stream from the repository service.

```java
RepositoryService repositoryService = processEngine.getRepositoryService();

DmnModelInstance dmnModelInstance = repositoryService
  .getDmnModelInstance("decisionDefinitionId");

InputStream modelInputStream = repositoryService
  .getDecisionModel("decisionDefinitionId");

InputStream diagramInputStream = repositoryService
  .getDecisionDiagram("decisionDefinitionId");
```

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

### Example Diagnostics Data Structure

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/process-engine/diagnostics-data.md

This JSON object represents the structure of the diagnostics data collected by Operaton, including installation details, product information, environment specifics, and usage statistics.

```json
{
    "installation": "8343cc7a-8ad1-42d4-97d2-43452c0bdfa3",
    "product": {
      "name": "Operaton BPM Runtime",
      "version": "2.1.2",
      "edition": "community",
      "internals": {
        "database": {
          "vendor": "h2",
          "version": "1.4.190 (2015-10-11)"
        },
        "application-server": {
          "vendor": "Wildfly",
          "version": "WildFly Full 19.0.0.Final (WildFly Core 11.0.0.Final) - 2.0.30.Final"
        },
        "jdk": {
          "version": "14.0.2",
          "vendor": "Oracle Corporation"
        },
        "commands": {
          "StartProcessInstanceCmd": {"count": 40},
          "FetchExternalTasksCmd":  {"count": 100}
        },
        "metrics": {
          "process-instances": { "count": 936 },
          "flow-node-instances": { "count": 6125 },
          "decision-instances": { "count": 140 },
          "executed-decision-elements": { "count": 732 }
        },
        "data-collection-start-date": "2022-11-30T15:53:20.386+0100",
        "operaton-integration": [
          "spring-boot-starter",
          "operaton-bpm-run"
        ],
        "webapps": [
          "cockpit",
          "admin"
        ]
      }
    }
}
```

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

### Starting a Process Instance by Message (Simplified Methods)

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/reference/bpmn20/events/message-events.md

Provides simplified methods to start a process instance directly using a message name, optionally with a business key and process variables.

```APIDOC
## Start Process Instance by Message

### Description
Starts a process instance using a referenced message. Can optionally include a business key and process variables.

### Methods
1. `ProcessInstance startProcessInstanceByMessage(String messageName)`
2. `ProcessInstance startProcessInstanceByMessage(String messageName, Map<String, Object> processVariables)`
3. `ProcessInstance startProcessInstanceByMessage(String messageName, String businessKey, Map<String, Object> processVariables)`

### Parameters
- **messageName** (String) - Required - The name of the message to start the process instance.
- **processVariables** (Map<String, Object>) - Optional - A map of process variables to set.
- **businessKey** (String) - Optional - The business key for the process instance.
```

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

### Accessing and Setting Process Variables

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/process-engine/scripting.md

Use the `execution` object to get and set process variables. This example demonstrates retrieving a variable 'x' and setting a new variable 'y' based on 'x'.

```java
// get process variable
sum = execution.getVariable('x')

// set process variable
execution.setVariable('y', x + 15)
```

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

### Groovy Script Task Example

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/process-engine/scripting.md

Defines a BPMN 2.0 script task that uses a Groovy script to sum elements of an input array. Ensure the 'inputArray' variable is provided when starting the process.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
                   targetNamespace="http://operaton.org/example">
  <process id="process" isExecutable="true">
    <startEvent id="start"/>
    <sequenceFlow id="sequenceFlow1" sourceRef="start" targetRef="task"/>
    <scriptTask id="task" name="Groovy Script" scriptFormat="groovy">
      <script>
        <![CDATA[
        sum = 0

        for ( i in inputArray ) {
          sum += i
        }

        println "Sum: " + sum
        ]]>
      </script>
    </scriptTask>
    <sequenceFlow id="sequenceFlow2" sourceRef="task" targetRef="end"/>
    <endEvent id="end"/>
  </process>
</definitions>
```

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

### Full Process Engine Configuration Example

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/process-engine/process-engine-bootstrapping.md

An example of a complete `operaton.cfg.xml` file, including database connection details, schema update settings, and mail server configuration. This file is parsed as a Spring configuration.

```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="processEngineConfiguration" class="org.operaton.bpm.engine.impl.cfg.StandaloneProcessEngineConfiguration">

    <property name="jdbcUrl" value="jdbc:h2:mem:operaton;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" />

    <property name="jobExecutorActivate" value="false" />

    <property name="mailServerHost" value="mail.my-corp.com" />
    <property name="mailServerPort" value="5025" />
  </bean>

</beans>
```

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

### Get BPMN Model Instance by Process Definition ID

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/model-api/bpmn-model-api/repository-service.md

Retrieve a BPMN model instance by querying for the process definition ID. This requires starting a process instance first to obtain a definition ID.

```java
public void testRepositoryService() {
  runtimeService.startProcessInstanceByKey(PROCESS_KEY);
  String processDefinitionId = repositoryService.createProcessDefinitionQuery()
    .processDefinitionKey(PROCESS_KEY).singleResult().getId();
  BpmnModelInstance modelInstance = repositoryService.getBpmnModelInstance(processDefinitionId);
}
```

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

### Defining Message Events in BPMN

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/reference/bpmn20/events/message-events.md

Declares two message events, 'newInvoiceMessage' and 'paymentMessage', referenced by a start event and an intermediate catching event respectively. This example demonstrates the basic structure for defining and referencing messages within a BPMN process.

```xml
<definitions id="definitions"
  xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
  xmlns:operaton="http://activiti.org/bpmn"
  targetNamespace="Examples"
  xmlns:tns="Examples">

  <message id="newInvoice" name="newInvoiceMessage" />
  <message id="payment" name="paymentMessage" />

  <process id="invoiceProcess">

    <startEvent id="messageStart" >
        <messageEventDefinition messageRef="newInvoice" />
    </startEvent>
    ...
    <intermediateCatchEvent id="paymentEvt" >
        <messageEventDefinition messageRef="payment" />
    </intermediateCatchEvent>
    ...
  </process>
</definitions>
```

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

### Logback Configuration Example

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/logging.md

Example Logback configuration file (`logback.xml`) for Operaton. It sets up a console appender with a specific pattern and configures logging levels for Operaton and common dependencies.

```xml
<configuration>

  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
    <!-- encoders are assigned the type
         ch.qos.logback.classic.encoder.PatternLayoutEncoder by default -->
    <encoder>
      <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
    </encoder>
  </appender>

  <!-- Operaton-->
  <logger name="org.operaton" level="info" />

  <!-- common dependencies -->
  <logger name="org.apache.ibatis" level="info" />
  <logger name="javax.activation" level="info" />
  <logger name="org.springframework" level="info" />

  <root level="debug">
    <appender-ref ref="STDOUT" />
  </root>

</configuration>
```

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

### Start Subprocess from its Start Event

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/process-engine/process-instance-modification.md

Cancel an active activity and then start a subprocess from its designated start event. This allows for a controlled restart of a specific subprocess.

```java
ProcessInstance processInstance = runtimeService.createProcessInstanceQuery().singleResult();
runtimeService.createProcessInstanceModification(processInstance.getId())
  .cancelAllForActivity("declineLoanApplication")
  .startBeforeActivity("subProcessStartEvent")
  .execute();
```

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

### Install Dependencies

Source: https://github.com/operaton/documentation/blob/main/README.md

Installs project dependencies using npm ci. Ensure Node.js 18 or newer is installed.

```bash
npm ci
```

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

### Create Queries

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/testing/assert-examples.md

Demonstrates the creation of various query objects using static helper methods.

```java
TaskQuery taskQuery = taskQuery();
JobQuery jobQuery = jobQuery();
ProcessInstanceQuery processInstanceQuery = processInstanceQuery();
ExecutionQuery executionQuery = executionQuery();
```

```java
assertThat(processInstance).task(taskQuery().taskAssignee("fozzie")).hasCandidateGroup("human-resources-department");
```

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

### Start Case Execution Manually (Fluent API)

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/reference/cmmn11/classic-vs-fluent.md

Use the fluent API to manually start a case execution. Variables can be set before starting.

```java
caseService
  .withCaseExecution(caseExecutionId)
  .manualStart();

Map<String, Object> variables = new HashMap<String, Object>();
variables.put("aVariableToSet", "aValueToSet");

caseService
  .withCaseExecution(caseExecutionId)
  .setVariables(variables)
  .manualStart();
```

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

### Configure Asynchronous Process Instance Start

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/process-engine/transactions-in-processes.md

Enable asynchronous instantiation of a process instance using the 'operaton:asyncBefore' extension attribute on a start event. Execution will be deferred, and listeners will not be invoked synchronously.

```xml
<startEvent id="theStart" name="Invoice Received" operaton:asyncBefore="true" />
```

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

### Run Migration with Gradle

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/update/camunda-to-operaton.md

Execute the Gradle wrapper with the init.gradle script to run the OpenRewrite migration. The active recipe for the migration must be specified.

```bash
./gradlew --init-script init.gradle rewriteRun \
  -Drewrite.activeRecipe=org.operaton.rewrite.MigrateFromCamunda
```

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

### Create a Simple Process

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/model-api/bpmn-model-api/fluent-builder-api.md

Use `Bpmn.createProcess()` to start building a model. Call `done()` to finalize and return the model instance.

```java
BpmnModelInstance modelInstance = Bpmn.createProcess()
  .startEvent()
  .userTask()
  .endEvent()
  .done();
```

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

### Build Migration Plan for Completeness Validation

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/process-engine/process-instance-migration.md

Example of creating a migration plan for completeness validation. This plan maps the 'archiveApplication' activity to itself.

```java
MigrationPlan migrationPlan = processEngine.getRuntimeService()
  .createMigrationPlan("exampleProcess:1", "exampleProcess:2")
  .mapActivities("archiveApplication", "archiveApplication")
  .build();
```

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

### Start Event Subprocess Directly

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/process-engine/process-instance-modification.md

Use this snippet to start an event subprocess by directly targeting its start event. This method does not interrupt the currently active activity.

```java
ProcessInstance processInstance = ...;
runtimeService.createProcessInstanceModification(processInstance.getId())
  .startBeforeActivity("eventSubProcessStartEvent")
  .execute();
```

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

### Passing Business Key to Signal Start Event

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/reference/bpmn20/events/signal-events.md

Configures a signal event to pass a business key to a process instance that starts with a Signal Start Event.

```xml
<signalEventDefinition signalRef="newCustomerSignal">
    <extensionElements>
          <operaton:in businessKey="${execution.processBusinessKey}" />
    </extensionElements>
</signalEventDefinition>
```

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

### Build Static Site

Source: https://github.com/operaton/documentation/blob/main/README.md

Generates the static site for Operaton documentation in the 'build' directory.

```bash
npm run build
```

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

### Create and Initialize NodeJS Project

Source: https://github.com/operaton/documentation/blob/main/docs/get-started/quick-start/service-task.md

Creates a new directory for the worker, navigates into it, and initializes a new NodeJS project with default settings.

```sh
mkdir charge-card-worker
cd ./charge-card-worker
npm init -y
```

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

### Gradle Initialization Script for Migration

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/update/camunda-to-operaton.md

Configure an init.gradle file to apply the OpenRewrite plugin and specify the Operaton migration recipe for Gradle projects. This script sets up the necessary dependencies and configurations for the migration.

```groovy
initscript {
  repositories {
    maven { url "https://plugins.gradle.org/m2" }
  }
  dependencies {
    classpath("org.openrewrite:plugin:7.25.0")
  }
}

rootProject {
  plugins.apply(org.openrewrite.gradle.RewritePlugin)
  dependencies {
    rewrite("org.operaton:migrate-camunda-recipe:1.0.1")
  }

  afterEvaluate {
    if (repositories.isEmpty()) {
      repositories {
        mavenLocal()
        mavenCentral()
      }
    } else {
      repositories {
        mavenLocal()
      }
    }
  }
}
```

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

### Start Process from its Start Event

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/process-engine/process-instance-modification.md

Cancel an active activity and then restart the entire process from its initial start event. This is a comprehensive way to reset and re-run a process instance.

```java
ProcessInstance processInstance = runtimeService.createProcessInstanceQuery().singleResult();
runtimeService.createProcessInstanceModification(processInstance.getId())
  .cancelAllForActivity("declineLoanApplication")
  .startBeforeActivity("processStartEvent")
  .execute();
```

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

### Start Activity and Set Variable

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/process-engine/process-instance-modification.md

This modification starts a new activity and sets a variable before the activity begins. Ensure the variable is present before the new activity starts to meet process requirements.

```java
ProcessInstance processInstance = runtimeService.createProcessInstanceQuery().singleResult();
runtimeService.createProcessInstanceModification(processInstance.getId())
  .startBeforeActivity("acceptLoanApplication")
  .setVariable("approver", "joe")
  .cancelAllForActivity("declineLoanApplication")
  .execute();
```

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

### Timer Start Event - Recurring

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/reference/bpmn20/events/timer-events.md

Defines a timer start event that will trigger a process instance 4 times at 5-minute intervals, starting on March 11, 2022, at 12:13 UTC+01.

```XML
<startEvent id="theStart">
  <timerEventDefinition>
    <timeCycle>R4/2022-03-11T12:13+01/PT5M</timeCycle>
  </timerEventDefinition>
</startEvent>
```

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

### Manually Start Case Task with Local Variables

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/reference/cmmn11/tasks/case-task.md

Demonstrates how to manually start a case task using `CaseService` and set local variables. When `local="true"` is used for `operaton:in`, only these explicitly set local variables are mapped.

```java
caseService
  .withCaseExecution(caseTaskExecutionId)
  .setVariable("var1", "abc")
  .setVariableLocal("var2", "def")
  .manualStart();
```

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

### Process Archive XML Example

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/reference/deployment-descriptors/tags/process-archive.md

Configures a process archive named 'loan-approval' to deploy to 'my-engine'. Includes two BPMN resources and sets custom properties for undeploy behavior, scanning, and resource suffixes.

```xml
<process-archive name="loan-approval">
  <process-engine>my-engine</process-engine>
  <resource>bpmn/invoice.bpmn</resource>
  <resource>bpmn/order-resource.bpmn</resource>
  <properties>
    <property name="isDeleteUponUndeploy">false</property>
    <property name="isScanForProcessDefinitions">true</property>
    <property name="additionalResourceSuffixes">groovy,py</property>
  </properties>
</process-archive>
```

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

### Assert Process Instance is Started

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/testing/assert-examples.md

Use this assertion to check if a process instance has been started.

```java
assertThat(processInstance).isStarted();
```

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

### Add Operaton Web Applications Starter to pom.xml

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/spring-boot-integration/webapps.md

Include this dependency in your pom.xml to enable the Operaton Web Applications starter.

```xml
<dependency>
  <groupId>org.operaton.bpm.springboot</groupId>
  <artifactId>operaton-bpm-spring-boot-starter-webapp</artifactId>
  <version>{project-version}</version>
</dependency>
```

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

### Manually Start Process Task with Local Variables

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/reference/cmmn11/tasks/process-task.md

Demonstrates how to manually start a process task using `CaseService` and set local variables that will be mapped into the called process instance when `local="true"` is configured for the `operaton:in` mapping.

```java
caseService
  .withCaseExecution(processTaskExecutionId)
  .setVariable("var1", "abc")
  .setVariableLocal("var2", "def")
  .manualStart();
```

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

### Start Process Instance by Message (Runtime Service Methods)

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/reference/bpmn20/events/message-events.md

These methods on the runtime service allow starting a process instance directly using a message name. Overloads support adding business keys and process variables.

```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);
```

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

### Create Simple GET Request

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/reference/connect/http-connector.md

Initiate a simple HTTP GET request to a specified URL.

```java
http.createRequest()
  .get()
  .url("http://operaton.org")
  .execute();
```

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

### Verify Java Installation

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/installation/operaton-bpm-run.md

Use this command to check if Java Runtime Environment 17 is installed on your system.

```sh
java -version
```

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

### Start Specific Process Instance by ID

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/process-engine/process-versioning.md

Starts a new process instance of a specific, older version by first querying for the process definition ID and then using `startProcessInstanceById`. Use this when you need to instantiate a particular version.

```java
ProcessDefinition pd = processEngine.getRepositoryService().createProcessDefinitionQuery()
    .processDefinitionKey("invoice")
    .processDefinitionVersion(1).singleResult();
processEngine.getRuntimeService().startProcessInstanceById(pd.getId());
```

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

### Quarkus Application Properties for Operaton

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/quarkus-integration/configuration.md

Example `application.properties` file for Quarkus demonstrating custom configurations for the Operaton process engine, job executor, and a custom data source.

```properties
# process engine configuration
quarkus.operaton.generic-config.cmmn-enabled=false
quarkus.operaton.generic-config.dmn-enabled=false
quarkus.operaton.generic-config.history=none

# job executor configuration
quarkus.operaton.job-executor.thread-pool.max-pool-size=12
quarkus.operaton.job-executor.thread-pool.queue-size=5
quarkus.operaton.job-executor.generic-config.max-jobs-per-acquisition=5
quarkus.operaton.job-executor.generic-config.lock-time-in-millis=500000
quarkus.operaton.job-executor.generic-config.wait-time-in-millis=7000
quarkus.operaton.job-executor.generic-config.max-wait=65000
quarkus.operaton.job-executor.generic-config.backoff-time-in-millis=5

# custom data source configuration and selection
quarkus.datasource.my-datasource.db-kind=h2
quarkus.datasource.my-datasource.username=operaton
quarkus.datasource.my-datasource.password=operaton
quarkus.datasource.my-datasource.jdbc.url=jdbc:h2:mem:operaton;TRACE_LEVEL_FILE=0;DB_CLOSE_ON_EXIT=FALSE
quarkus.operaton.datasource=my-datasource
```

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

### Build Migration Plan with Hierarchy Preservation

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/process-engine/process-instance-migration.md

Demonstrates how to create a migration plan by mapping activities. Ensure that migrated activities remain descendants of their closest migrating ancestor scope.

```java
MigrationPlan migrationPlan = processEngine.getRuntimeService()
  .createMigrationPlan("exampleProcess:1", "exampleProcess:2")
  .mapActivities("assessCreditWorthiness", "handleApplicationReceipt")
  .mapActivities("validateAddress", "validatePostalAddress")
  .build();
```

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

### Execute Migration Plan with Process Instance Query

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/process-engine/process-instance-migration.md

Select process instances for migration based on a `ProcessInstanceQuery`. The query should target instances of the source process definition.

```Java
MigrationPlan migrationPlan = ...;

ProcessInstanceQuery processInstanceQuery = runtimeService
  .createProcessInstanceQuery()
  .processDefinitionId(migrationPlan.getSourceProcessDefinitionId());

runtimeService.newMigration(migrationPlan)
  .processInstanceQuery(processInstanceQuery)
  .execute();
```

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

### Start Subprocess Execution

Source: https://github.com/operaton/documentation/blob/main/docs/documentation/user-guide/process-engine/process-instance-modification.md

Cancel an active activity and then start the execution of a subprocess. This is useful when the entire subprocess needs to be re-evaluated or re-executed.

```java
ProcessInstance processInstance = runtimeService.createProcessInstanceQuery().singleResult();
runtimeService.createProcessInstanceModification(processInstance.getId())
  .cancelAllForActivity("declineLoanApplication")
  .startBeforeActivity("evaluateLoanApplication")
  .execute();
```