Configuring Spin Integration
To use Spin with the process engine, the following is required:
- The Spin libraries must be on the engine’s classpath
- The Spin process engine plugin must be registered with the process engine
The following sections go into the details of integrating Spin with the process engine. Note that when you use a pre-built Camunda distribution, Spin is already integrated.
There are three types of Spin artifacts as follows.
camunda-spin-core is a jar that contains only the core Spin classes. It can be combined with single data format artifacts. Camunda provides the artifacts
camunda-spin-dataformat-xml-dom-jakarta for Jakarta XML Binding 4.0 support) that implement JSON and XML processing. These artifacts transitively pull in libraries they need. For example,
camunda-spin-dataformat-json-jackson has a dependency to
camunda-spin-dataformat-all is a fat jar that contains
camunda-spin-dataformat-xml-dom as well as all their dependencies. The dependencies are shaded into the
spinjar package namespace.
Note that the package relocation means that you cannot develop against the original namespaces. Example:
jackson-databind for object (de-)serialization. A common use case is declaring Jackson annotations in custom classes to finetune JSON handling. With relocated dependencies, annotations in the
com.fasterxml.jackson namespace will not be recognized by Spin. In that case, consider using
camunda-spin-core. Keep in mind the implications this may have as described in the Integration Use Cases section.
camunda-engine-plugin-spin is a process engine plugin that integrates Spin with a process engine. For example, it
registers variable serializers that enable the process engine to store Java objects as JSON.
Configuration properties of the Spin plugin
The Spin process engine plugin provides the following configuration options:
|Toggle the processing of External XML Entities (XXE) in an XML document. Disable to prevent
XXE attacks. Default value:
|Toggle the secure processing of an XML document.
Import the Camunda BOM to ensure that you use the right version of Spin that is tested to work with your version of the process engine.
All Spin artifacts have the group id
org.camunda.spin, so in order to import
camunda-spin-core, we can write:
<!-- The version is omitted here, because it is managed via the BOM.
Declare a concrete version if you do not use the BOM -->
Integration Use Cases
Depending on the application and process engine setup, it is recommended to use either
camunda-spin-core (plus individual data formats) or
camunda-spin-dataformat-all. The following sections explain when to use which for the most common use cases.
Embedded Process Engine
If your application manages its own process engine, then using
camunda-spin-core is the recommended approach. Declare the dependencies in the
compile scope so that the Spin libraries and their dependencies are added to your application when you bundle it. Configure
org.camunda.spin.plugin.impl.SpinProcessEnginePlugin as a process engine plugin according to the process engine plugin documentation.
Application with Camunda Spring Boot Starter
Add the dependencies to
camunda-spin-core (along with
camunda-spin-dataformat-xml-dom as needed) to your application. If you need to use Jakarta XML Binding 4.0 (e.g. Springboot version 3.x.x), use
camunda-spin-dataformat-xml-dom-jakarta instead of
The Spin process engine plugin will be automatically registered with the process engine.
Shared Process Engine
If you use a shared process engine, Spin is usually installed as a shared library in the application server. Check the installation guide for your application server for how to set up Spin with a shared engine. When using a pre-built distribution of Camunda Platform, Spin is already pre-configured.
Depending on the type of application server,
camunda-engine-plugin-spin should be used with either
camunda-spin-dataformat-all. In the pre-packaged distributions, the following artifacts are used:
camunda-spin-dataformat-allis provided in Tomcat’s shared library path. Using
camunda-spin-dataformat-allavoids classpath pollution with Spin’s dependencies. For example, this ensures that applications are not forced to use Spin’s version of Jackson.
camunda-spin-dataformat-xml-dom) are deployed as modules. Thanks to Wildfly’s module system, classpath pollution is not an issue. Whenever a process application is deployed, it receives an implicit module dependency to
If you want to program against the Spin APIs in your process application, you need to declare a dependency to Spin in your application. As Spin is provided by the application server, the following is important:
- Make sure to set the dependencies to scope
provided. This avoids that a copy of the dependencies is packaged with your application, resulting in various classloading problems at runtime.
- Make sure to depend on the same Spin artifacts that the application server provides, i.e. either