Maven Coordinates

The Camunda DMN engine is released to Maven Central.

Start by importing the to ensure correct dependency management.

Next, include the camunda-engine-dmnartifact in the dependencies section.

Building a DMN Engine

To build a new DMN engine, create a DMN engine configuration.Configure it as needed and then build a new DMN engine from it.

Configuration of the DMN Engine

The DMN engine configuration allows you add a custom decision table . A decision table evaluation listener isnotified after a decision table has been evaluated. It receives an evaluation eventwhich contains the result of the evaluation. You can decide if thelistener should be notified before or after the default listeners.

  1. // create default DMN engine configuration
  2. DmnEngineConfiguration configuration = DmnEngineConfiguration
  3.     .createDefaultDmnEngineConfiguration();
  5. // instantiate the listener
  6. DmnDecisionTableEvaluationListener myListener = ...;
  8. // notify before default listeners
  9. configuration.getCustomPreDecisionTableEvaluationListeners()
  10.   .add(myListener);
  12. // notify after default listeners
  13. configuration.getCustomPostDecisionTableEvaluationListeners()
  14.   .add(myListener);

A specialized evaluation listener is the metric collector, which records the number of executed decisionelements. This metric can be used to monitor the workload of a decision engine.

  1. // create default DMN engine configuration
  2. DmnEngineConfiguration configuration = DmnEngineConfiguration
  3.     .createDefaultDmnEngineConfiguration();
  5. // create your metric collector
  6. DmnEngineMetricCollector metricCollector = ...;
  8. // set the metric collector
  9. configuration.setEngineMetricCollector(metricCollector);

The DMN engine configuration allows you add a custom . A decision evaluation listener isnotified after a decision with all the required decisions has been evaluated. It receives an evaluation eventwhich contains the result of the evaluation. You can decide if thelistener should be notified before or after the default listeners.

  1. // create default DMN engine configuration
  2. DmnEngineConfiguration configuration = DmnEngineConfiguration
  3.     .createDefaultDmnEngineConfiguration();
  5. // instantiate the listener
  7. // notify before default listeners
  8. configuration.getCustomPreDecisionEvaluationListeners()
  9.   .add(myListener);
  11. // notify after default listeners
  12. configuration.getCustomPostDecisionEvaluationListeners()
  13.   .add(myListener);

Customizing and Extending the DMN Engine

Please be aware that these APIs are not part of the public API and may change in later releases.

The has further customization andextension points.

It is possible to customize the transformation of DMN by providing a DMN transformer or configuring the .

  1. // with a default DMN engine configuration
  3.   .createDefaultDmnEngineConfiguration();
  5. // instantiate transform listener
  6. DmnTransformListener myTransformListener = ... ;
  8. // add the transform listener
  9. configuration.getTransformer()
  10.   .getTransformListeners()
  11.   .add(myTransformListener);

While the transform listener allows modifying of the transformed objects, it does not support instantiating custom subclasses.This can be achieved using a custom transform handler.

A transform handler is registered for a given type like a DecisionTable.

First, implement a transform handler which can transform a decision table.

Then, register an instance of the handler in the default DMN transformer element handler registry.

  1. // with a default DMN engine configuration
  2. DefaultDmnEngineConfiguration configuration = (DefaultDmnEngineConfiguration) DmnEngineConfiguration
  3.   .createDefaultDmnEngineConfiguration();
  5. // add the handler
  6. configuration.getTransformer()
  7.   .getElementTransformHandlerRegistry()
  8.   .addHandler(DecisionTable.class, new MyDecisionTableHandler());

The DMN engine supports a set of built-in . It is possible to override existing types with new types.

Assume you want to support a local date format type.To achieve this, override the existing date transformer by implementing a custom transformer:

  1. public class GermanDateDataTypeTransformer extends DateDataTypeTransformer {
  3.   protected SimpleDateFormat format = new SimpleDateFormat("dd.MM.yyyy HH:mm:ss");
  5.   protected Date transformString(String value) {
  6.     try {
  7.       return format.parse(value);
  8.     }
  9.     catch (ParseException e) {
  10.       throw new IllegalArgumentException(e);
  11.     }
  12.   }
  13. }

Then, register an instance of the handler in the default DMN transformer element handler registry:

  1. // with a default DMN engine configuration
  2. DefaultDmnEngineConfiguration configuration = (DefaultDmnEngineConfiguration) DmnEngineConfiguration
  4. // add the data type transformer,
  5. // overriding the existing type "date":
  6. configuration
  7.   .getTransformer()
  8.   .getDataTypeTransformerRegistry()
  9.   .addTransformer("date", new GermanDateDataTypeTransformer());

It is also possible to add a new data type by implementing a new transformer and registering it for a non-existing type name:

  2. DefaultDmnEngineConfiguration configuration = (DefaultDmnEngineConfiguration) DmnEngineConfiguration
  3.   .createDefaultDmnEngineConfiguration();
  5. // add the data type transformer for custom type "currency"
  6. configuration
  7.   .getTransformer()
  8.   .getDataTypeTransformerRegistry()
  9.   .addTransformer("currency", new currencyTypeTransformer());

The DMN engine supports a subset of the DMN 1.1 hit policies. It is possible to implement new hit policies oroverride an existing hit policy implementation.

A has multiple expressions which are evaluated when the table is executed.The default expression language for every expression type can be configured.The following expression types exist:

  • Input Expression: Used to specify the input of a column in a decisiontable. The default language for input expressions in the DMN engine isJUEL.
  • Input Entry: Used to specify the condition of a rule in a decisiontable. The default language for input entries in the DMN engine isFEEL.
  • Output Entry: Used to specify the output of a rule in a decisiontable. The default language for output entries in the DMN engine isJUEL.
    The default expression language of a DMN decision literal expression can also be configured, the default in the DMN engine is JUEL.

It is possible to change the default expression language on the DMN engine configuration:

  1. DefaultDmnEngineConfiguration configuration = (DefaultDmnEngineConfiguration) DmnEngineConfiguration
  2.   .createDefaultDmnEngineConfiguration();
  4. configuration
  5.   .setDefaultInputExpressionExpressionLanguage("javascript");

Please note that the chosen language must be available in the classpath. Bydefault JUEL and FEEL are available. The default FEEL implementationis only supported for input entries.

If the JDK includes a JavaScriptimplementation like Rhino or Nashorn, then javascript is available as well.

It is also possible to use other script languages like groovy, python or ruby.Just make sure that the corresponding libraries are available on the classpath at runtime.

The default DMN engine resolves the supported expression and script languagesusing different providers.

To evaluate JUEL expressions, the DMN engine uses the configured in theDMN engine configuration. To use another implementation of the Unified Expression Language, replace this implementation.

  1. // with a default DMN engine configuration
  2. DefaultDmnEngineConfiguration configuration = (DefaultDmnEngineConfiguration) DmnEngineConfiguration
  3.   .createDefaultDmnEngineConfiguration();
  5. // set a custom el provider
  6. configuration.setElProvider(new MyElProvider());

To configure the FEEL engine used you can provide a custom FeelEngineFactory.

  1. // with a default DMN engine configuration
  2. DefaultDmnEngineConfiguration configuration = (DefaultDmnEngineConfiguration) DmnEngineConfiguration
  3.   .createDefaultDmnEngineConfiguration();
  5. // set a custom feel engine factory
  6. configuration.setFeelEngineFactory(new MyFeelEngineFactory());

Script languages are resolved by the . To customize the script engine resolving, provide an own implementation.

  1. // with a default DMN engine configuration
  2. DefaultDmnEngineConfiguration configuration = (DefaultDmnEngineConfiguration) DmnEngineConfiguration
  3.   .createDefaultDmnEngineConfiguration();
  5. // set custom script engine resolver
  6. configuration.setScriptEngineResolver(new MyScriptEngineResolver());

Logging

The DMN engine uses SLF4J as logging API. The artifactdoes not have a dependency to any of the existing backends. This means thatyou can choose which backend you want to use. One example would be LOGBack, orif you want to use Java util logging, you could use the slf4j-jdk14 artifact.For more information on how to configure and use SLF4J, please refer to the.