> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aseeflow.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Decisions in the Process Engine Repository

To evaluate a DMN decision in ASEE Flow, 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.3] 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 `.dmn` or
`.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.

```java theme={null}
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
a `.dmn` or `.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.

```xml theme={null}
<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]

```xml theme={null}
<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 `id` attribute from the XML file.
* `name`: The DMN decision `name` attribute 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 theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="https://www.omg.org/spec/DMN/20191111/MODEL/" 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:

* `id`: GENERATED
* `key`: `my-decision`
* `name`: `My Decision`
* `version`: 1

### 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.

## Versioning of Decision Requirements Graph

In addition to the decision definitions, the [decision requirements graph](/reference/dmn/drg) (i.e., the `definitions` element in the XML) of a deployed DMN resource is transformed into a *Decision Requirements Definition*. It has, among others, these attributes:

* `id`: The unique identifier of the Decision Requirements Definition generated by the
  platform.
* `key`: The definitions `id` attribute from the XML file.
* `name`: The definitions `name` attribute from the XML file.
* `version`: The version of the Decision Requirements Definition generated by the platform.

Note that the decision requirements definition is only created if the DMN resource contains more than one decision.

### The Decision Requirements Definition Key

The decision requirements definition key is equivalent to the `id` attribute of the `definitions` element in the DMN XML.

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="https://www.omg.org/spec/DMN/20191111/MODEL/" 
             id="my-drg" 
             name="My DRG" 
             namespace="http://camunda.org/schema/1.0/dmn">
  <!-- ... -->
</definitions>
```

When deploying the above DMN XML file, a decision requirements definition having the following properties is created:

* `id`: GENERATED
* `key`: `my-drg`
* `name`: `My DRG`
* `version`: 1

### The Decision Requirements Definition Version

When a decision requirements graph is deployed, it is checked whether a definition with the same key is already deployed.
If not, the decision requirements definition is assigned version `1` for this key. If a decision requirements definition with the same
key already exists, the newly deployed definition will become a new version of
the existing one, increasing its version by one.

Note that the versions of the contained decision definitions can be different from the decision requirements definition if they are also deployed inside other DMN resources, as a single decision inside a DMN resource, or added later.

## Querying the Decision Repository

All deployed decision definitions and decision requirements definitions can be queried by the repository service API.

### Querying Decision Definitions

Get a decision definition with the id "decisionDefinitionId":

```java theme={null}
DecisionDefinition decisionDefinition = processEngine
  .getRepositoryService()
  .getDecisionDefinition("decisionDefinitionId");
```

Query for a decision definition with the key "decisionDefinitionKey" and
version 1:

```java theme={null}
DecisionDefinition decisionDefinition = processEngine
  .getRepositoryService()
  .createDecisionDefinitionQuery()
  .decisionDefinitionKey("decisionDefinitionKey")
  .decisionDefinitionVersion(1)
  .singleResult();
```

Query for the latest version of decision definition with the key "decisionDefinitionKey":

```java theme={null}
DecisionDefinition decisionDefinition = processEngine
  .getRepositoryService()
  .createDecisionDefinitionQuery()
  .decisionDefinitionKey("decisionDefinitionKey")
  .latestVersion()
  .singleResult();
```

Query for all versions of decision definitions with the key
"decisionDefinitionKey":

```java theme={null}
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.

```java theme={null}
RepositoryService repositoryService = processEngine.getRepositoryService();

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

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

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

### Querying Decision Requirements Definitions

The decision requirements definitions can be queried in a similar way to the decision definitions.

```java theme={null}
// query for the latest version of a decision requirements definition by key
DecisionRequirementsDefinition decisionRequirementsDefinition = processEngine
  .getRepositoryService()
  .createDecisionRequirementsDefinitionQuery()
  .decisionRequirementsDefinitionKey(key)
  .latestVersion()
  .singleResult();
  
// query for all versions of decision requirements definitions by name
List<DecisionRequirementsDefinition> decisionRequirementsDefinitions = processEngine
  .getRepositoryService()
  .createDecisionRequirementsDefinitionQuery()
  .decisionRequirementsDefinitionName(name)
  .list();  
```

## Authorizations for Querying the Decision Repository

The user needs the `READ` permission on the resource `DECISION_DEFINITION` to
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.

To query decision requirements definitions, the user needs the `READ` permission on the resource `DECISION_REQUIREMENTS_DEFINITION`. The
resource id of the authorization is the key of the decision requirements definitions.

For more information about authorizations, please refer to the [Authorization
Service](/user-guide/process-engine/authorization-service) section.

## Cockpit

Deployed decision definitions can be viewed in the [Cockpit] webapp.

[Deployment]: /user-guide/process-engine/deployments

[DMN 1.3]: /reference/dmn

[Process Application]: /user-guide/process-applications

[Process Archive]: /reference/deployment-descriptors/tags/process-archive

[Cockpit]: /webapps/cockpit/dmn