This library aims to provide a REST client for Camunda Platform 7 REST API for SpringBoot. In doing so it offers \"remote\" implementations of Camunda Platform 7 Engine Java API. This project is highly iterative and releases the functionality in small increments. Please check the support matrix to find out if the functionality you require is already supported by the library.
"},{"location":"index.html#quick-start","title":"Quick Start","text":"If you just want to start using the library, please consult our Getting Started guide.
"},{"location":"index.html#working-example","title":"Working Example","text":"We provide a working example demonstrating some features of the library. See our Examples section for usage and configuration.
"},{"location":"index.html#user-guide","title":"User Guide","text":"If you have any questions regarding configuration of Camunda BPM Feign please have a look at our User Guide.
"},{"location":"index.html#contribution","title":"Contribution","text":"If you want to contribute to this project, feel free to do so. Start with Contributing guide.
"},{"location":"getting-started.html","title":"Getting started","text":"Note
If you are using the extension from an application containing Camunda BPM Engine classes on the classpath, please check the Working Example section of our user guide.
Note
You can also use the generated feign clients directly without using the Camunda Services. Please check out the Feign Example section of our user guide.
"},{"location":"getting-started.html#install-dependency","title":"Install Dependency","text":"First install the extension dependency and configure Feign and Feign client:
<properties>\n <camunda-platform-7-rest-client-spring-boot.version>7.20.2-SNAPSHOT</camunda-platform-7-rest-client-spring-boot.version>\n <spring-cloud.version>2023.0.1</spring-cloud.version>\n</properties>\n\n<dependencyManagement>\n<dependencies>\n <dependency>\n <groupId>org.springframework.cloud</groupId>\n <artifactId>spring-cloud-dependencies</artifactId>\n <version>${spring-cloud.version}</version>\n <type>pom</type>\n <scope>import</scope>\n </dependency>\n</dependencies>\n</dependencyManagement>\n<dependencies>\n<dependency>\n <groupId>org.camunda.community.rest</groupId>\n <artifactId>camunda-platform-7-rest-client-spring-boot-starter</artifactId>\n <version>${camunda-platform-7-rest-client-spring-boot.version}</version>\n</dependency>\n<dependency>\n <groupId>org.springframework.cloud</groupId>\n <artifactId>spring-cloud-starter-openfeign</artifactId>\n</dependency>\n<dependency>\n <groupId>io.github.openfeign</groupId>\n <artifactId>feign-httpclient</artifactId>\n</dependency>\n</dependencies>\nNote
Please make sure your Spring Cloud version matches your Spring Boot version as described in the Spring Cloud documentation
"},{"location":"getting-started.html#configuration","title":"Configuration","text":"In your client code, activate the usage of REST client by adding the following annotation to your configuration:
@Configuration\n@EnableCamundaRestClient\npublic class MyClientConfiguration {\n\n}\nIn order to configure the Feign client, make sure to provide usual feign client configuration (e.g. using application.yml). To set up the engine base URL, please set up the properties:
feign:\n client:\n config:\n default:\n url: \"http://your-process-engine-host/engine-rest/\"\nThere is also the possibility to configure a different URL for each feign client (even though this is a very uncommon setup):
feign:\n client:\n config:\n processInstance:\n url: \"http://your-process-engine-host/engine-rest/\"\n processDefinition:\n url: \"http://your-process-engine-host/engine-rest/\"\n message:\n url: \"http://your-process-engine-host/engine-rest/\"\n ...\nTo access the remote API, inject the remote API implementation:
@Component\npublic class MyClient {\n\n private RuntimeService runtimeService;\n\n public MyClient(@Qualifier(\"remote\") RuntimeService runtimeService) {\n this.runtimeService = runtimeService;\n }\n\n public void start() {\n this.runtimeService\n .startProcessInstanceByKey(\"my_process_key\");\n }\n\n public void correlate() {\n this.runtimeService\n .createMessageCorrelation(\"message_received\")\n .processInstanceBusinessKey(\"WAIT_FOR_MESSAGE\")\n .correlateAllWithResult();\n }\n}\nThere are several ways in which you may contribute to this project.
Please file an issue in our issue tracking system.
"},{"location":"developer-guide/contribution.html#submit-a-pull-request","title":"Submit a Pull Request","text":"If you found a solution to an open issue and implemented it, we would be happy to add your contribution in the code base. For doing so, please create a pull request. Prior to that, please make sure you
develop branchIf you are interested in developing and building the project please read the following the instructions carefully.
"},{"location":"developer-guide/project-setup.html#version-control","title":"Version control","text":"To get sources of the project, please execute:
git clone https://github.com/camunda-communit-hub/camunda-platform-7-rest-client-spring-boot.git\ncd camunda-platform-7-rest-client-spring-boot\nWe are using gitflow in our git SCM for naming b ranches. That means that you should start from master branch, create a feature/<name> out of it and once it is completed create a pull request containing it. Please squash your commits before submitting and use semantic commit messages, if possible.
Perform the following steps to get a development setup up and running.
./mvnw clean install\nBy default, the build command will ignore the run of failsafe Maven plugin executing the integration tests (usual JUnit tests with class names ending with ITest). In order to run integration tests, please call from your command line:
./mvnw -Pitest failsafe:verify\nYou can choose the used Camunda version by specifying the profile camunda-ee or camunda-ce. The default version is a Community Edition. Specify -Pcamunda-ee to switch to Camunda Enterprise edition. This will require a valid Camunda license. You can put it into a file ~/.camunda/license.txt and it will be detected automatically.
We are using MkDocs for generation of a static site documentation and rely on markdown as much as possible.
Note
If you want to develop your docs in 'live' mode, run mkdocs serve and access the http://localhost:8000/ from your browser.
For creation of documentation, please run:
"},{"location":"developer-guide/project-setup.html#generation-of-javadoc-and-sources","title":"Generation of JavaDoc and Sources","text":"By default, the sources and javadoc API documentation are not generated from the source code. To enable this:
./mvnw clean install -Pcommunity-action-maven-release -Dgpg.skip=true\nTo start applications, either use your IDE and create run configuration for the class:
org.camunda.community.rest.example.standalone.CamundaRestClientExampleApplicationorg.camunda.community.rest.example.processapplication.CamundaRestClientExampleApplicationWithEngineProvidedAlternatively, you can run them from the command line:
./mvn spring-boot:run -f examples/example\n./mvn spring-boot:run -f examples/example-provided\nGitHub Actions are building all branches on commit hook (for codecov). In addition, a GitHub Actions are used to build PRs and all branches.
"},{"location":"developer-guide/project-setup.html#release-management","title":"Release Management","text":"The release is produced by using the GitHub feature to \"Publish a Release\". To do so, please \"close a milestone\" and a special action will generate automatically collected issues and PRs to generate the Release notes. It will create a tag, which will be built if this release get published. Now \"Publish release\" and the GH action will create a new release and publish it into Camunda Artifactory and Maven Central Staging. To release it to the public, please create an issue and assign it to someone of Camunda @camunda-community-hub/devrel
"},{"location":"developer-guide/project-setup.html#what-modules-get-deployed-to-repository","title":"What modules get deployed to repository","text":"Every Maven module is enabled by default. If you want to change this, please provide the property
<maven.deploy.skip>true</maven.deploy.skip>\ninside the corresponding pom.xml. Currently, all examples are EXCLUDED from publication into Maven Central.
If you are visiting this project for the first time, please check the following sections:
The library supports the following features:
"},{"location":"introduction/features.html#general","title":"General","text":"RuntimeService, RepositoryService, TaskService, ExternalTaskService, HistoryService#startProcessInstanceByKey()#startProcessInstanceById()#createProcessInstanceQuery()#correlateMessage(), #createMessageCorrelation()#signalEventReceived(), #createSignalEvent()#signal()#getVariable(),#getVariables(), #getVariableTyped(), #getVariablesTyped()#getVariableLocal(),#getVariablesLocal(), #getVariableLocalTyped(), #getVariablesLocalTyped()#setVariable(),#setVariables(), #setVariableTyped(), #setVariablesTyped()#removeVariable(),#removeVariables()#setVariableLocal(),#setVariablesLocal(), #setVariableLocalTyped(), #setVariablesLocalTyped()#removeVariableLocal(),#removeVariablesLocal()#createIncidentQuery()#createIncident(), #resolveIncident()#setAnnotationForIncidentById(), #clearAnnotationForIncidentById()#suspendProcessInstanceByProcessDefinitionKey(), #activateProcessInstanceByProcessDefinitionKey()#suspendProcessInstanceByProcessDefinitionId(), #activateProcessInstanceByProcessDefinitionId()#suspendProcessInstanceById(), #activateProcessInstanceById()#updateProcessInstanceSuspensionState()#deleteProcessInstance(), #deleteProcessInstanceIfExists(), #deleteProcessInstances(), #deleteProcessInstancesIfExists(), #deleteProcessInstancesAsync()#createEventSubscriptionQuery()#createExecutionQuery()#createProcessDefinitionQuery()#updateDecisionDefinitionHistoryTimeToLive(), #updateProcessDefinitionHistoryTimeToLive()#createDeployment()#deleteDeployment(), #deleteDeploymentCascade()#createDeploymentQuery()#deleteProcessDefinition()#updateProcessDefinitionSuspensionState()#getBpmnModelInstance()#createTaskQuery()#claim(), #defer(), #resolve(), #addCandidateGroup(), #deleteCandidateGroup(), #addCadidateUser(), #deleteCandidateUser()#addUserIdentityLink(), #addGroupIdentityLink(), #deleteUserIdentityLink(), #deleteGroupIdentityLink(),#complete()#deleteTasks()#setPriority(), #setOwner(), #setAssignee(), #saveTask()#handleBpmnError(), #handleEscalation()#getVariable(),#getVariables(), #getVariableTyped(), #getVariablesTyped()#getVariableLocal(),#getVariablesLocal(), #getVariableLocalTyped(), #getVariablesLocalTyped()#setVariable(),#setVariables(), #setVariableTyped(), #setVariablesTyped()#removeVariable(),#removeVariables()#setVariableLocal(),#setVariablesLocal(), #setVariableLocalTyped(), #setVariablesLocalTyped()#removeVariableLocal(),#removeVariablesLocal()We are not aiming to replace the existing External Task Client, but still provide an alternative implementation for some methods.
#complete()#handleBpmnError()#handleFailure()#createHistoricProcessInstanceQuery()#evaluateDecisionById(),#evaluateDecisionByKey()#evaluateDecisionTableById(),#evaluateDecisionTableByKey().#evaluateDecisionTableByKeyAndVersion()Support query methods of RuntimeService for:
Support methods of ManagementService for:
Is the library missing a feature important for you? Please report it.
"},{"location":"introduction/motivation.html","title":"Motivation","text":"During the development of Camunda Platform 7 process applications you have to choose if your applications is either using Camunda Platform 7 Engine or is Camunda Platform 7 Engine. Depending on this decision, you are accessing Camunda Platform 7 via REST or Java API.
While Camunda Engine Core API provides well-designed and easy-accessible programming interface for Java, the usage of REST interface requires additional development. In order to enable the usage of REST API from Java and allow for easy integration into Spring Boot applications, the Camunda Platform 7 REST Client Spring-Boot library has been developed.
So instead of usage a hand-written or generated client, this library provides you the same access to a remote Camunda Platform 7 engine as the Java API provides to local Camunda. The difference between using and being disappears.
"},{"location":"introduction/solution.html","title":"Solution","text":"The library uses the popular Java REST client OpenFeign embedded into Spring-Cloud-Feign-Starter and provides implementations of Java Camunda Platform 7 Engine Core API, accessing the remote engine via REST API.
In doing so, the remote version of the Camunda Engine API can be easily integrated in existing application using a SpringBoot Starter.
Depending on your usage scenario, you can choose from two starters shipped by the library.
"},{"location":"user-guide/index.html","title":"Overview","text":"The user guide consists of several sections.
"},{"location":"user-guide/index.html#examples","title":"Examples","text":"The camunda-platform-7-rest-client-spring-boot uses HTTP to access a remote Camunda Platform 7 REST API. If any errors occur on this access, Camunda Platform 7 REST API will send with corresponding HTTP error code and embed information about the error into http response. camunda-platform-7-rest-client-spring-boot tries to parse this response and throw an exception on the client side similar to the original exception thrown on the remote Camunda Platform 7 Engine.
By default, the library tries to decode HTTP codes and will throw a RemoteProcessEngineException. If the response decoding was successful, the cause of the thrown RemoteProcessEngineException will be the instance of the exception class thrown on remote Camunda Platform 7 engine and the reason of the latter exception will be the original reason from the server. This behavior can be changed by configuration, so that the remotely thrown exception will be thrown locally, if the decoding was successful. For this the property camunda.rest.client.error-decoding.wrap-exceptions has to be set to false.
If anything goes wrong on HTTP error decoding, the RemoteProcessEngineException will contain a generic message extracted from the REST call. If the error decoding is deactivated, FeignException is wrapping any exception occurring during the remote access.
By default, the HTTP error decoding is switched on and the library reacts on HTTP codes 400 and 500. Also by default all exceptions will be wrapped in a RemoteProcessEngineException. Those defaults can be changed by setting the following properties.
In order to configure it, a block of properties e.g. in application.yml is required. Here are the defaults:
camunda:\n rest:\n client:\n error-decoding:\n enabled: true\n http-codes: 400, 500\n wrap-exceptions: true\nInfo
If you are using the remote version of the ExternalTaskService this will report HTTP 404 if you try to complete a non-existing task. By changing the camunda.rest.client.error-decoding.http-codes property you can cover this response too.
We provide demonstrating the usage of the library, depending on the context.
"},{"location":"user-guide/examples.html#standalone-usage","title":"Standalone usage","text":"The example demonstrates the usage of the library accessing a process engine via REST from an arbitrary SpringBoot application. The client executes the following steps:
"},{"location":"user-guide/examples.html#timing-overview-of-the-example","title":"Timing overview of the example","text":"Initial offset Repeat Invoked method 8.0 sec - Get deployed processes 10.0 sec 5 sec Start process 12.5 sec 5 sec Send signal 13.0 sec 5 sec Correlate message"},{"location":"user-guide/examples.html#how-does-it-work","title":"How does it work","text":"The application uses the library by adding it to the classpath via Apache Maven dependency. That is:
<dependency>\n <groupId>org.camunda.community.rest</groupId>\n <artifactId>camunda-platform-7-rest-client-spring-boot-starter</artifactId>\n <version>${project.version}</version>\n</dependency>\nIn order to activate the library, the @EnableCamundaRestClient has been put on the configuration class of the application. The interesting part is now the ProcessClient component. This Spring Component has several methods marked with @Scheduled annotation to demonstrate the time-based execution of desired functionality. To do so, the component has two injected resources, both marked with the @Qualifier(\"remote\") annotation. This annotation indicates that the remote version of the Camunda API services are used.
In order to configure the library, a block of properties e.g. in application.yml is required. The values specify the location of the remote process engine:
feign:\n client:\n config:\n default:\n url: \"http://localhost:8083/engine-rest/\"\nTo run this example, you will need the server part from the next example. To activate the server part only, please run from command line:
mvn clean install\nmvn -f examples/example -Prun\nmvn -f examples/example-provided -Prun-server-only\nThe example demonstrates the usage of the library for accessing a process engine via REST from a Camunda Platform 7 process application. The key difference to the previous example is that the required Camunda classes are already present on the classpath and an engine is initialized and is running.
Imagine the process engine has the following process deployed:
The client (running technically in the same JVM, but accessing the engine via REST) again executes the following steps:
"},{"location":"user-guide/examples.html#timing-overview-of-the-example_1","title":"Timing overview of the example","text":"Initial offset Repeat Invoked method 8.0 sec - Get deployed processes 10.0 sec 5 sec Start process 12.5 sec 5 sec Send signal 13.0 sec 5 sec Correlate message"},{"location":"user-guide/examples.html#how-does-it-work_1","title":"How does it work","text":"The application uses the library by adding it to the classpath via Apache Maven dependency. That is:
<dependency>\n <groupId>org.camunda.community.rest</groupId>\n <artifactId>camunda-platform-7-rest-client-spring-boot-starter-provided</artifactId>\n <version>${project.version}</version>\n</dependency>\nNOTE: Please note that we use a different starter. The suffix provided in the artifact name indicates that the engine is already a part of the application and doesn't need to be put on classpath.
In order to activate the library, the @EnableCamundaRestClient has been put on the configuration class of the application. The interesting part is now the ProcessClient component. This Spring Component has several methods marked with @Scheduled annotation to demonstrate the time-based execution of desired functionality. To do so, the component has two injected resources, both marked with the @Qualifier(\"remote\") annotation. This annotation indicates that the remote version of the Camunda API services are used.
In order to configure the library, a block of properties e.g. in application.yml is required:
feign:\n client:\n config:\n default:\n url: \"http://localhost:8083/engine-rest/\"\nThe example demonstrates the usage of the library for accessing the REST from a Camunda Platform 7 process application using the generated feign clients. The difference to the previous examples is that no Camunda dependency is required on the classpath, as the feign clients are used directly.
"},{"location":"user-guide/examples.html#how-does-it-work_2","title":"How does it work","text":"The application uses the library by adding it to the classpath via Apache Maven dependency. That is:
<dependency>\n <groupId>org.camunda.community.rest</groupId>\n <artifactId>camunda-platform-7-rest-client-spring-boot-openapi</artifactId>\n <version>${project.version}</version>\n</dependency>\nIn order to activate the library, the @EnableCamundaFeignClients has to be put on the configuration class of the application. The interesting part is now the ProcessClient component. This Spring Component has several methods marked with @Scheduled annotation to demonstrate the time-based execution of desired functionality. To do so, the component has injected the needed feign clients as resources.
In order to configure the library, the same block of properties e.g. in application.yml as before is required:
feign:\n client:\n config:\n ...\nOpenFeign library used in the camunda-platform-7-rest-client-spring-boot has a high-configurable logging facility. In order to configure it, a block of properties e.g. in application.yml is required:
logging:\n level:\n org.camunda.community.rest.client.RuntimeServiceClient: DEBUG\n org.camunda.community.rest.client.RepositoryServiceClient: DEBUG\n org.camunda.community.rest.client.ExternalTaskServiceClient: DEBUG\nIn order to enable Request/Response logging, you need to configure additional Feign logging by providing a factory bean:
import feign.Logger;\n\n@Configuration\npublic class MyConfiguration {\n /**\n * Full debug of feign client, including request/response\n */\n @Bean\n public Logger.Level feignLoggerLevel() {\n return Logger.Level.FULL;\n }\n}\nHere are currently implemented methods. The version behind the service name denotes the last version in which the service has been touched.
"},{"location":"user-guide/support-matrix.html#task-service-006","title":"Task Service @ 0.0.6","text":"# createTaskQuery# claim# deleteTask# deleteTasks# resolveTask# complete# saveTask# setAssignee# setPriority# setVariable# setVariables# setVariableLocal# setVariablesLocal# getVariable# getVariableLocal# getVariableTyped# getVariableLocal# getVariableLocalTyped# getVariables# getVariablesLocal# getVariablesTyped# getVariablesLocalTyped# removeVariable# removeVariableLocal# removeVariables# removeVariablesLocal# getIdentityLinksForTask# addCandidateUser# addCandidateGroup# addUserIdentityLink# addGroupIdentityLink# deleteCandidateUser# deleteCandidateGroup# deleteUserIdentityLink# deleteGroupIdentityLink# handleBpmnError# handleEscalation# startProcessInstanceByKey# startProcessInstanceById# correlateMessage# createMessageCorrelation# createProcessInstanceQuery# signal# signalEventReceived# createSignalEvent# getVariable# getVariables# setVariable# setVariables# removeVariable# removeVariables# getVariableTyped# getVariablesTyped# setVariableTyped# setVariablesTyped# getVariableLocal# getVariablesLocal# setVariableLocal# setVariablesLocal# removeVariableLocal# removeVariablesLocal# getVariableTypedLocal# getVariablesTypedLocal# setVariableTypedLocal# setVariablesTypedLocal# createIncidentQuery# createIncident# resolveIncident# setAnnotationForIncidentById# clearAnnotationForIncidentById# suspendProcessInstanceByProcessDefinitionKey# activateProcessInstanceByProcessDefinitionKey# suspendProcessInstanceByProcessDefinitionId# activateProcessInstanceByProcessDefinitionId# suspendProcessInstanceById# activateProcessInstanceById# updateProcessInstanceSuspensionState# deleteProcessInstance# deleteProcessInstanceIfExists# deleteProcessInstances# deleteProcessInstancesIfExists# deleteProcessInstancesAsync# createProcessDefinitionQuery# updateDecisionDefinitionHistoryTimeToLive# updateProcessDefinitionHistoryTimeToLive# createDeployment# deleteDeployment# deleteDeploymentCascade# createDeploymentQuery# deleteProcessDefinition# updateProcessDefinitionSuspensionState# getBpmnModelInstance# complete# handleBpmnError# handleFailure# createHistoricProcessInstanceQuery# evaluateDecisionById# evaluateDecisionByKey# evaluateDecisionTableById# evaluateDecisionTableByKey# evaluateDecisionTableByKeyAndVersion# createEventSubscriptionQuery# createExecutionQueryThis library aims to provide a REST client for Camunda Platform 7 REST API for SpringBoot. In doing so it offers \"remote\" implementations of Camunda Platform 7 Engine Java API. This project is highly iterative and releases the functionality in small increments. Please check the support matrix to find out if the functionality you require is already supported by the library.
"},{"location":"index.html#quick-start","title":"Quick Start","text":"If you just want to start using the library, please consult our Getting Started guide.
"},{"location":"index.html#working-example","title":"Working Example","text":"We provide a working example demonstrating some features of the library. See our Examples section for usage and configuration.
"},{"location":"index.html#user-guide","title":"User Guide","text":"If you have any questions regarding configuration of Camunda BPM Feign please have a look at our User Guide.
"},{"location":"index.html#contribution","title":"Contribution","text":"If you want to contribute to this project, feel free to do so. Start with Contributing guide.
"},{"location":"getting-started.html","title":"Getting started","text":"Note
If you are using the extension from an application containing Camunda BPM Engine classes on the classpath, please check the Working Example section of our user guide.
Note
You can also use the generated feign clients directly without using the Camunda Services. Please check out the Feign Example section of our user guide.
"},{"location":"getting-started.html#install-dependency","title":"Install Dependency","text":"First install the extension dependency and configure Feign and Feign client:
<properties>\n <camunda-platform-7-rest-client-spring-boot.version>7.20.2-SNAPSHOT</camunda-platform-7-rest-client-spring-boot.version>\n <spring-cloud.version>2023.0.1</spring-cloud.version>\n</properties>\n\n<dependencyManagement>\n<dependencies>\n <dependency>\n <groupId>org.springframework.cloud</groupId>\n <artifactId>spring-cloud-dependencies</artifactId>\n <version>${spring-cloud.version}</version>\n <type>pom</type>\n <scope>import</scope>\n </dependency>\n</dependencies>\n</dependencyManagement>\n<dependencies>\n<dependency>\n <groupId>org.camunda.community.rest</groupId>\n <artifactId>camunda-platform-7-rest-client-spring-boot-starter</artifactId>\n <version>${camunda-platform-7-rest-client-spring-boot.version}</version>\n</dependency>\n<dependency>\n <groupId>org.springframework.cloud</groupId>\n <artifactId>spring-cloud-starter-openfeign</artifactId>\n</dependency>\n<dependency>\n <groupId>io.github.openfeign</groupId>\n <artifactId>feign-httpclient</artifactId>\n</dependency>\n</dependencies>\nNote
Please make sure your Spring Cloud version matches your Spring Boot version as described in the Spring Cloud documentation
"},{"location":"getting-started.html#configuration","title":"Configuration","text":"In your client code, activate the usage of REST client by adding the following annotation to your configuration:
@Configuration\n@EnableCamundaRestClient\npublic class MyClientConfiguration {\n\n}\nIn order to configure the Feign client, make sure to provide usual feign client configuration (e.g. using application.yml). To set up the engine base URL, please set up the properties:
feign:\n client:\n config:\n default:\n url: \"http://your-process-engine-host/engine-rest/\"\nThere is also the possibility to configure a different URL for each feign client (even though this is a very uncommon setup):
feign:\n client:\n config:\n processInstance:\n url: \"http://your-process-engine-host/engine-rest/\"\n processDefinition:\n url: \"http://your-process-engine-host/engine-rest/\"\n message:\n url: \"http://your-process-engine-host/engine-rest/\"\n ...\nTo access the remote API, inject the remote API implementation:
@Component\npublic class MyClient {\n\n private RuntimeService runtimeService;\n\n public MyClient(@Qualifier(\"remote\") RuntimeService runtimeService) {\n this.runtimeService = runtimeService;\n }\n\n public void start() {\n this.runtimeService\n .startProcessInstanceByKey(\"my_process_key\");\n }\n\n public void correlate() {\n this.runtimeService\n .createMessageCorrelation(\"message_received\")\n .processInstanceBusinessKey(\"WAIT_FOR_MESSAGE\")\n .correlateAllWithResult();\n }\n}\nThere are several ways in which you may contribute to this project.
Please file an issue in our issue tracking system.
"},{"location":"developer-guide/contribution.html#submit-a-pull-request","title":"Submit a Pull Request","text":"If you found a solution to an open issue and implemented it, we would be happy to add your contribution in the code base. For doing so, please create a pull request. Prior to that, please make sure you
develop branchIf you are interested in developing and building the project please read the following the instructions carefully.
"},{"location":"developer-guide/project-setup.html#version-control","title":"Version control","text":"To get sources of the project, please execute:
git clone https://github.com/camunda-communit-hub/camunda-platform-7-rest-client-spring-boot.git\ncd camunda-platform-7-rest-client-spring-boot\nWe are using gitflow in our git SCM for naming b ranches. That means that you should start from master branch, create a feature/<name> out of it and once it is completed create a pull request containing it. Please squash your commits before submitting and use semantic commit messages, if possible.
Perform the following steps to get a development setup up and running.
./mvnw clean install\nBy default, the build command will ignore the run of failsafe Maven plugin executing the integration tests (usual JUnit tests with class names ending with ITest). In order to run integration tests, please call from your command line:
./mvnw -Pitest failsafe:verify\nYou can choose the used Camunda version by specifying the profile camunda-ee or camunda-ce. The default version is a Community Edition. Specify -Pcamunda-ee to switch to Camunda Enterprise edition. This will require a valid Camunda license. You can put it into a file ~/.camunda/license.txt and it will be detected automatically.
We are using MkDocs for generation of a static site documentation and rely on markdown as much as possible.
Note
If you want to develop your docs in 'live' mode, run mkdocs serve and access the http://localhost:8000/ from your browser.
For creation of documentation, please run:
"},{"location":"developer-guide/project-setup.html#generation-of-javadoc-and-sources","title":"Generation of JavaDoc and Sources","text":"By default, the sources and javadoc API documentation are not generated from the source code. To enable this:
./mvnw clean install -Pcommunity-action-maven-release -Dgpg.skip=true\nTo start applications, either use your IDE and create run configuration for the class:
org.camunda.community.rest.example.standalone.CamundaRestClientExampleApplicationorg.camunda.community.rest.example.processapplication.CamundaRestClientExampleApplicationWithEngineProvidedAlternatively, you can run them from the command line:
./mvn spring-boot:run -f examples/example\n./mvn spring-boot:run -f examples/example-provided\nGitHub Actions are building all branches on commit hook (for codecov). In addition, a GitHub Actions are used to build PRs and all branches.
"},{"location":"developer-guide/project-setup.html#release-management","title":"Release Management","text":"The release is produced by using the GitHub feature to \"Publish a Release\". To do so, please \"close a milestone\" and a special action will generate automatically collected issues and PRs to generate the Release notes. It will create a tag, which will be built if this release get published. Now \"Publish release\" and the GH action will create a new release and publish it into Camunda Artifactory and Maven Central Staging. To release it to the public, please create an issue and assign it to someone of Camunda @camunda-community-hub/devrel
"},{"location":"developer-guide/project-setup.html#what-modules-get-deployed-to-repository","title":"What modules get deployed to repository","text":"Every Maven module is enabled by default. If you want to change this, please provide the property
<maven.deploy.skip>true</maven.deploy.skip>\ninside the corresponding pom.xml. Currently, all examples are EXCLUDED from publication into Maven Central.
If you are visiting this project for the first time, please check the following sections:
The library supports the following features:
"},{"location":"introduction/features.html#general","title":"General","text":"RuntimeService, RepositoryService, TaskService, ExternalTaskService, HistoryService#startProcessInstanceByKey()#startProcessInstanceById()#createProcessInstanceQuery()#correlateMessage(), #createMessageCorrelation()#signalEventReceived(), #createSignalEvent()#signal()#getVariable(),#getVariables(), #getVariableTyped(), #getVariablesTyped()#getVariableLocal(),#getVariablesLocal(), #getVariableLocalTyped(), #getVariablesLocalTyped()#setVariable(),#setVariables(), #setVariableTyped(), #setVariablesTyped()#removeVariable(),#removeVariables()#setVariableLocal(),#setVariablesLocal(), #setVariableLocalTyped(), #setVariablesLocalTyped()#removeVariableLocal(),#removeVariablesLocal()#createIncidentQuery()#createIncident(), #resolveIncident()#setAnnotationForIncidentById(), #clearAnnotationForIncidentById()#suspendProcessInstanceByProcessDefinitionKey(), #activateProcessInstanceByProcessDefinitionKey()#suspendProcessInstanceByProcessDefinitionId(), #activateProcessInstanceByProcessDefinitionId()#suspendProcessInstanceById(), #activateProcessInstanceById()#updateProcessInstanceSuspensionState()#deleteProcessInstance(), #deleteProcessInstanceIfExists(), #deleteProcessInstances(), #deleteProcessInstancesIfExists(), #deleteProcessInstancesAsync()#createEventSubscriptionQuery()#createExecutionQuery()#createProcessDefinitionQuery()#updateDecisionDefinitionHistoryTimeToLive(), #updateProcessDefinitionHistoryTimeToLive()#createDeployment()#deleteDeployment(), #deleteDeploymentCascade()#createDeploymentQuery()#deleteProcessDefinition()#updateProcessDefinitionSuspensionState()#getBpmnModelInstance()#createTaskQuery()#claim(), #defer(), #resolve(), #addCandidateGroup(), #deleteCandidateGroup(), #addCadidateUser(), #deleteCandidateUser()#addUserIdentityLink(), #addGroupIdentityLink(), #deleteUserIdentityLink(), #deleteGroupIdentityLink(),#complete()#deleteTasks()#setPriority(), #setOwner(), #setAssignee(), #saveTask()#handleBpmnError(), #handleEscalation()#getVariable(),#getVariables(), #getVariableTyped(), #getVariablesTyped()#getVariableLocal(),#getVariablesLocal(), #getVariableLocalTyped(), #getVariablesLocalTyped()#setVariable(),#setVariables(), #setVariableTyped(), #setVariablesTyped()#removeVariable(),#removeVariables()#setVariableLocal(),#setVariablesLocal(), #setVariableLocalTyped(), #setVariablesLocalTyped()#removeVariableLocal(),#removeVariablesLocal()We are not aiming to replace the existing External Task Client, but still provide an alternative implementation for some methods.
#complete()#handleBpmnError()#handleFailure()#fetchAndLock()#extendLock(),#lock(),#unlock()#setPriority()#getTopicNames()#getExternalTaskErrorDetails()#createExternalTaskQuery()#setRetries(),#setRetriesAsync(),#updateRetries()#createHistoricProcessInstanceQuery()#evaluateDecisionById(),#evaluateDecisionByKey()#evaluateDecisionTableById(),#evaluateDecisionTableByKey().#evaluateDecisionTableByKeyAndVersion()Support query methods of RuntimeService for:
Support methods of ManagementService for:
Is the library missing a feature important for you? Please report it.
"},{"location":"introduction/motivation.html","title":"Motivation","text":"During the development of Camunda Platform 7 process applications you have to choose if your applications is either using Camunda Platform 7 Engine or is Camunda Platform 7 Engine. Depending on this decision, you are accessing Camunda Platform 7 via REST or Java API.
While Camunda Engine Core API provides well-designed and easy-accessible programming interface for Java, the usage of REST interface requires additional development. In order to enable the usage of REST API from Java and allow for easy integration into Spring Boot applications, the Camunda Platform 7 REST Client Spring-Boot library has been developed.
So instead of usage a hand-written or generated client, this library provides you the same access to a remote Camunda Platform 7 engine as the Java API provides to local Camunda. The difference between using and being disappears.
"},{"location":"introduction/solution.html","title":"Solution","text":"The library uses the popular Java REST client OpenFeign embedded into Spring-Cloud-Feign-Starter and provides implementations of Java Camunda Platform 7 Engine Core API, accessing the remote engine via REST API.
In doing so, the remote version of the Camunda Engine API can be easily integrated in existing application using a SpringBoot Starter.
Depending on your usage scenario, you can choose from two starters shipped by the library.
"},{"location":"user-guide/index.html","title":"Overview","text":"The user guide consists of several sections.
"},{"location":"user-guide/index.html#examples","title":"Examples","text":"The camunda-platform-7-rest-client-spring-boot uses HTTP to access a remote Camunda Platform 7 REST API. If any errors occur on this access, Camunda Platform 7 REST API will send with corresponding HTTP error code and embed information about the error into http response. camunda-platform-7-rest-client-spring-boot tries to parse this response and throw an exception on the client side similar to the original exception thrown on the remote Camunda Platform 7 Engine.
By default, the library tries to decode HTTP codes and will throw a RemoteProcessEngineException. If the response decoding was successful, the cause of the thrown RemoteProcessEngineException will be the instance of the exception class thrown on remote Camunda Platform 7 engine and the reason of the latter exception will be the original reason from the server. This behavior can be changed by configuration, so that the remotely thrown exception will be thrown locally, if the decoding was successful. For this the property camunda.rest.client.error-decoding.wrap-exceptions has to be set to false.
If anything goes wrong on HTTP error decoding, the RemoteProcessEngineException will contain a generic message extracted from the REST call. If the error decoding is deactivated, FeignException is wrapping any exception occurring during the remote access.
By default, the HTTP error decoding is switched on and the library reacts on HTTP codes 400 and 500. Also by default all exceptions will be wrapped in a RemoteProcessEngineException. Those defaults can be changed by setting the following properties.
In order to configure it, a block of properties e.g. in application.yml is required. Here are the defaults:
camunda:\n rest:\n client:\n error-decoding:\n enabled: true\n http-codes: 400, 500\n wrap-exceptions: true\nInfo
If you are using the remote version of the ExternalTaskService this will report HTTP 404 if you try to complete a non-existing task. By changing the camunda.rest.client.error-decoding.http-codes property you can cover this response too.
We provide demonstrating the usage of the library, depending on the context.
"},{"location":"user-guide/examples.html#standalone-usage","title":"Standalone usage","text":"The example demonstrates the usage of the library accessing a process engine via REST from an arbitrary SpringBoot application. The client executes the following steps:
"},{"location":"user-guide/examples.html#timing-overview-of-the-example","title":"Timing overview of the example","text":"Initial offset Repeat Invoked method 8.0 sec - Get deployed processes 10.0 sec 5 sec Start process 12.5 sec 5 sec Send signal 13.0 sec 5 sec Correlate message"},{"location":"user-guide/examples.html#how-does-it-work","title":"How does it work","text":"The application uses the library by adding it to the classpath via Apache Maven dependency. That is:
<dependency>\n <groupId>org.camunda.community.rest</groupId>\n <artifactId>camunda-platform-7-rest-client-spring-boot-starter</artifactId>\n <version>${project.version}</version>\n</dependency>\nIn order to activate the library, the @EnableCamundaRestClient has been put on the configuration class of the application. The interesting part is now the ProcessClient component. This Spring Component has several methods marked with @Scheduled annotation to demonstrate the time-based execution of desired functionality. To do so, the component has two injected resources, both marked with the @Qualifier(\"remote\") annotation. This annotation indicates that the remote version of the Camunda API services are used.
In order to configure the library, a block of properties e.g. in application.yml is required. The values specify the location of the remote process engine:
feign:\n client:\n config:\n default:\n url: \"http://localhost:8083/engine-rest/\"\nTo run this example, you will need the server part from the next example. To activate the server part only, please run from command line:
mvn clean install\nmvn -f examples/example -Prun\nmvn -f examples/example-provided -Prun-server-only\nThe example demonstrates the usage of the library for accessing a process engine via REST from a Camunda Platform 7 process application. The key difference to the previous example is that the required Camunda classes are already present on the classpath and an engine is initialized and is running.
Imagine the process engine has the following process deployed:
The client (running technically in the same JVM, but accessing the engine via REST) again executes the following steps:
"},{"location":"user-guide/examples.html#timing-overview-of-the-example_1","title":"Timing overview of the example","text":"Initial offset Repeat Invoked method 8.0 sec - Get deployed processes 10.0 sec 5 sec Start process 12.5 sec 5 sec Send signal 13.0 sec 5 sec Correlate message"},{"location":"user-guide/examples.html#how-does-it-work_1","title":"How does it work","text":"The application uses the library by adding it to the classpath via Apache Maven dependency. That is:
<dependency>\n <groupId>org.camunda.community.rest</groupId>\n <artifactId>camunda-platform-7-rest-client-spring-boot-starter-provided</artifactId>\n <version>${project.version}</version>\n</dependency>\nNOTE: Please note that we use a different starter. The suffix provided in the artifact name indicates that the engine is already a part of the application and doesn't need to be put on classpath.
In order to activate the library, the @EnableCamundaRestClient has been put on the configuration class of the application. The interesting part is now the ProcessClient component. This Spring Component has several methods marked with @Scheduled annotation to demonstrate the time-based execution of desired functionality. To do so, the component has two injected resources, both marked with the @Qualifier(\"remote\") annotation. This annotation indicates that the remote version of the Camunda API services are used.
In order to configure the library, a block of properties e.g. in application.yml is required:
feign:\n client:\n config:\n default:\n url: \"http://localhost:8083/engine-rest/\"\nThe example demonstrates the usage of the library for accessing the REST from a Camunda Platform 7 process application using the generated feign clients. The difference to the previous examples is that no Camunda dependency is required on the classpath, as the feign clients are used directly.
"},{"location":"user-guide/examples.html#how-does-it-work_2","title":"How does it work","text":"The application uses the library by adding it to the classpath via Apache Maven dependency. That is:
<dependency>\n <groupId>org.camunda.community.rest</groupId>\n <artifactId>camunda-platform-7-rest-client-spring-boot-openapi</artifactId>\n <version>${project.version}</version>\n</dependency>\nIn order to activate the library, the @EnableCamundaFeignClients has to be put on the configuration class of the application. The interesting part is now the ProcessClient component. This Spring Component has several methods marked with @Scheduled annotation to demonstrate the time-based execution of desired functionality. To do so, the component has injected the needed feign clients as resources.
In order to configure the library, the same block of properties e.g. in application.yml as before is required:
feign:\n client:\n config:\n ...\nOpenFeign library used in the camunda-platform-7-rest-client-spring-boot has a high-configurable logging facility. In order to configure it, a block of properties e.g. in application.yml is required:
logging:\n level:\n org.camunda.community.rest.client.RuntimeServiceClient: DEBUG\n org.camunda.community.rest.client.RepositoryServiceClient: DEBUG\n org.camunda.community.rest.client.ExternalTaskServiceClient: DEBUG\nIn order to enable Request/Response logging, you need to configure additional Feign logging by providing a factory bean:
import feign.Logger;\n\n@Configuration\npublic class MyConfiguration {\n /**\n * Full debug of feign client, including request/response\n */\n @Bean\n public Logger.Level feignLoggerLevel() {\n return Logger.Level.FULL;\n }\n}\nHere are currently implemented methods. The version behind the service name denotes the last version in which the service has been touched.
"},{"location":"user-guide/support-matrix.html#task-service-006","title":"Task Service @ 0.0.6","text":"# createTaskQuery# claim# deleteTask# deleteTasks# resolveTask# complete# saveTask# setAssignee# setPriority# setVariable# setVariables# setVariableLocal# setVariablesLocal# getVariable# getVariableLocal# getVariableTyped# getVariableLocal# getVariableLocalTyped# getVariables# getVariablesLocal# getVariablesTyped# getVariablesLocalTyped# removeVariable# removeVariableLocal# removeVariables# removeVariablesLocal# getIdentityLinksForTask# addCandidateUser# addCandidateGroup# addUserIdentityLink# addGroupIdentityLink# deleteCandidateUser# deleteCandidateGroup# deleteUserIdentityLink# deleteGroupIdentityLink# handleBpmnError# handleEscalation# startProcessInstanceByKey# startProcessInstanceById# correlateMessage# createMessageCorrelation# createProcessInstanceQuery# signal# signalEventReceived# createSignalEvent# getVariable# getVariables# setVariable# setVariables# removeVariable# removeVariables# getVariableTyped# getVariablesTyped# setVariableTyped# setVariablesTyped# getVariableLocal# getVariablesLocal# setVariableLocal# setVariablesLocal# removeVariableLocal# removeVariablesLocal# getVariableTypedLocal# getVariablesTypedLocal# setVariableTypedLocal# setVariablesTypedLocal# createIncidentQuery# createIncident# resolveIncident# setAnnotationForIncidentById# clearAnnotationForIncidentById# suspendProcessInstanceByProcessDefinitionKey# activateProcessInstanceByProcessDefinitionKey# suspendProcessInstanceByProcessDefinitionId# activateProcessInstanceByProcessDefinitionId# suspendProcessInstanceById# activateProcessInstanceById# updateProcessInstanceSuspensionState# deleteProcessInstance# deleteProcessInstanceIfExists# deleteProcessInstances# deleteProcessInstancesIfExists# deleteProcessInstancesAsync# createProcessDefinitionQuery# updateDecisionDefinitionHistoryTimeToLive# updateProcessDefinitionHistoryTimeToLive# createDeployment# deleteDeployment# deleteDeploymentCascade# createDeploymentQuery# deleteProcessDefinition# updateProcessDefinitionSuspensionState# getBpmnModelInstance# complete# handleBpmnError# handleFailure# createHistoricProcessInstanceQuery# evaluateDecisionById# evaluateDecisionByKey# evaluateDecisionTableById# evaluateDecisionTableByKey# evaluateDecisionTableByKeyAndVersion# createEventSubscriptionQuery# createExecutionQuery# createExernalTaskQuery# fetchAndLock# extendLock# unlock# lock# getTopicNames# getExternalTaskErrorDetails# setPriority# setRetries# setRetriesAsync# updateRetries# createExernalTaskQuery# fetchAndLock# extendLock# unlock# lock# getTopicNames# getExternalTaskErrorDetails# setPriority# setRetries# setRetriesAsync# updateRetries