Decisions in the Process Engine Repository
To evaluate a DMN decision in Camunda BPM platform, it has to be part of a Deployment. After a decision has been deployed, it can be referenced by its key and version. The platform supports DMN 1.1 XML files.
Deploying a Decision
To deploy a DMN decision you can either use the Repository Service or add it to
a Process Application. The platform will recognize all files with a
.dmn11.xml file extension as DMN resources.
Deploying a decision using the Repository Service
Use the Repository Service to create a new Deployment and add DMN resources to it. The following code, for example, will create a new deployment for a DMN file in the classpath.
String resourceName = "MyDecision.dmn11.xml"; Deploymnet deployment = processEngine .getRepositoryService() .createDeployment() .addClasspathResource(resourceName) .deploy();
Deploying a decision with a Process Application
If you deploy a Process Application, you can add the DMN file to your
archive as other resources, like BPMN processes. The DMN files must have
.dmn11.xml file extension to be recognized as DMN resource.
If your Process Archive is set up to scan for process definitions, it will automatically deploy the DMN definitions too. This is the default.
<process-archive name="loan-approval"> <properties> <property name="isScanForProcessDefinitions">true</property> </properties> </process-archive>
Otherwise, you have to specify the DMN resources explicitly in the Process Archive
<process-archive name="loan-approval"> <resource>bpmn/invoice.bpmn</resource> <resource>dmn/assign-approver.dmn</resource> <properties> <property name="isScanForProcessDefinitions">false</property> </properties> </process-archive>
Versioning of Decisions
When a DMN resource is deployed to the platform, every supported DMN Decision is transformed into a Decision Definition. A decision definition represents a single DMN decision in the platform. It has, among others, these attributes:
id: The unique identifier of the Decision Definition generated by the platform.
key: The DMN decision
idattribute from the XML file.
name: The DMN decision
nameattribute from the XML file.
version: The version of the Decision Definition generated by the platform.
The Decision Definition Key
The decision definition key is equivalent to the
id attribute of the DMN
decision in the DMN XML.
<?xml version="1.0" encoding="UTF-8"?> <definitions xmlns="http://www.omg.org/spec/DMN/20151101/dmn11.xsd" id="definitions" name="definitions" namespace="http://camunda.org/schema/1.0/dmn"> <decision id="my-decision" name="My Decision"> <decisionTable> <output id="output1"/> </decisionTable> </decision> </definitions>
When deploying the above DMN XML file, a decision definition having the following properties is created:
The Decision Definition Version
When a decision is deployed, it is checked whether a definition with the same key is already deployed.
If not, the decision definition is assigned version
1 for this key. If a decision definition with the same
key already exists, the newly deployed decision definition will become a new version of
the existing one, increasing its version by one.
This versioning of decision definitions allows the user to update decisions, but still be able to use previous decision versions if needed.
The Decision Definition Id
The id of a decision definition is not equivalent to the
id attribute of
the DMN XML decision. It is generated by the platform as unique identifier.
This means a decision definition id directly corresponds to a decision
definition key and version combination.
Reference a Decision Definition
To reference a deployed decision definition in the context of the platform, either the decision definition id or the decision definition key and version is used. If a decision definition key is used but no version is specified, the default is to use the latest version of the decision definition.
Querying the Decision Repository
All deployed decision definitions can be queried by the repository service API.
Get a decision definition with the id “decisionDefinitionId”:
DecisionDefinition decisionDefinition = processEngine .getRepositoryService() .getDecisionDefinition("decisionDefinitionId");
Query for a decision definition with the key “decisionDefinitionKey” and version 1:
DecisionDefinition decisionDefinition = processEngine .getRepositoryService() .createDecisionDefinitionQuery() .decisionDefinitionKey("decisionDefinitionKey") .decisionDefinitionVersion(1) .singleResult();
Query for the latest version of decision definition with the key “decisionDefinitionKey”:
DecisionDefinition decisionDefinition = processEngine .getRepositoryService() .createDecisionDefinitionQuery() .decisionDefinitionKey("decisionDefinitionKey") .latestVersion() .singleResult();
Query for all versions of decision definitions with the key “decisionDefinitionKey”:
List<DecisionDefinition> decisionDefinitions = processEngine .getRepositoryService() .createDecisionDefinitionQuery() .decisionDefinitionKey("decisionDefinitionKey") .list();
Additionally, the repository service can be used to get the DMN XML file, a DMN model instance or deployed diagram images.
RepositoryService repositoryService = processEngine.getRepositoryService(); DmnModelInstance dmnModelInstance = repositoryService .getDmnModelInstance("decisionDefinitionId"); InputStream modelInputStream = repositoryService .getDecisionModel("decisionDefinitionId"); InputStream diagramInputStream = repositoryService .getDecisionDiagram("decisionDefinitionId");
Authorizations for Querying Decisions
The user needs the
READ permission on the resource
query decision definitions. This permission is also required to retrieve decision
definitions, decision models and decision diagrams from the repository. The
resource id of the authorization is the decision definition key.
For more information about authorizations, please refer to the Authorization Service section.
Deployed decision definitions can be viewed in the Cockpit webapp.