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

# Decision Service in the Process Engine

The decision service is a part of the process engine's [Services API]. It allows
to evaluate a deployed decision definition independently from BPMN and CMMN.

## Evaluating a Decision

To evaluate a deployed decision, reference it by id or a combination of key and version. If
a key is used but no version is specified then the latest version of decision
definition with the given key is evaluated.

```java theme={null}
DecisionService decisionService = processEngine.getDecisionService();

VariableMap variables = Variables.createVariables()
  .putValue("status", "bronze")
  .putValue("sum", 1000);

DmnDecisionResult decisionResult = decisionService
  .evaluateDecisionByKey("decision-key")
  .variables(variables)
  .evaluate(); 
  
// alternatively for decision tables only
DmnDecisionTableResult decisionResult = decisionService
  .evaluateDecisionTableByKey("decision-key")
  .variables(variables)
  .evaluate(); 
```

### The Decision Key

The key of a decision definition is specified by the `id` attribute of the
`decision` element in the DMN XML. The different naming is related to the
[Versioning of Decisions]. Since a key can reference multiple versions of a
decision definition, the id specifies exactly one version.

### Passing Data

A decision may reference one or more variables. For example, a variable can be
referenced in an input expression or an input entry of a decision table. The
variables are passed to the decision service as key-value pairs. Each pair
specifies the name and the value of a variable.

For more information on the different expressions see the [DMN 1.3 reference].

## Authorizations for Evaluating Decisions

The user needs the permission `CREATE_INSTANCE` on the resource
`DECISION_DEFINITION` to evaluate decisions. The resource id of the
authorization is the decision definition key.

For more information about authorizations please refer to the [Authorization
Service] section.

## Working with the Decision Result

The result of an evaluation is called decision result. The decision result is a complex object
of type `DmnDecisionResult`. Think of it as a list of key-value pairs.

If the decision is implemented as [decision table] then each entry in the list represents one matched rule. The output entries of this
rule are represented by the key-value pairs. The key of a pair is specified by
the name of the output.

Instead, if the decision is implemented as [decision literal expression] then the list contains only one entry. This entry represents the expression value and is mapped by the variable name.

The decision result provides methods from interface `List<Map<String,
Object>>` and some convenience methods.

```java theme={null}
DmnDecisionResult decisionResult = ...;

// get the value of the single entry of the only matched rule
String singleEntry = decisionResult.getSingleResult().getSingleEntry();

// get the value of the result entry with name 'result' of the only matched rule
String result = decisionResult.getSingleResult().getEntry("result");

// get the value of the first entry of the second matched rule
String firstValue = decisionResult.get(1).getFirstEntry();

// get a list of all entries with the output name 'result' of all matched rules
List<String> results = decisionResult.collectEntries("result");

// shortcut to get the single output entry of the single rule result
// - combine getSingleResult() and getSingleEntry()
String result = decisionResult.getSingleEntry();
```

Note that the decision result also provides methods to get typed output entries.
A complete list of all methods can be found in the [Java Docs](https://docs.camunda.org/javadoc/camunda-bpm-platform/7.24/org/camunda/bpm/dmn/engine/DmnDecisionResult).

If the decision is implemented as [decision table] then it can also be evaluated using one of the
[evaluateDecisionTable](https://docs.camunda.org/javadoc/camunda-bpm-platform/7.24/org/camunda/bpm/engine/DecisionService.html##evaluateDecisionTableByKey\(java.lang.String\)) methods. In this case, the evaluation returns a [DmnDecisionTableResult](https://docs.camunda.org/javadoc/camunda-bpm-platform/7.24/org/camunda/bpm/dmn/engine/DmnDecisionTableResult.html) which is semantically equal and provide the same methods as a
`DmnDecisionResult`.

## History of Evaluated Decisions

When a decision is evaluated, a new history entry of type
`HistoricDecisionInstance` is created which contains the inputs and outputs of
the decision. The history can be queried by the history service.

```java theme={null}
List<HistoricDecisionInstance> historicDecisions = processEngine
  .getHistoryService()
  .createHistoricDecisionInstanceQuery()
  .decisionDefinitionKey("decision-key")
  .includeInputs()
  .includeOutputs()
  .list();
```

For more information about this, please refer to the [History for DMN Decisions].

[decision table]: /reference/dmn/decision-table

[decision literal expression]: /reference/dmn/decision-literal-expression

[Services API]: /user-guide/process-engine/process-engine-api#services-api

[DMN 1.3 reference]: /reference/dmn/decision-table

[Versioning of Decisions]: /user-guide/process-engine/decisions/repository#versioning-of-decisions

[Authorization Service]: /user-guide/process-engine/authorization-service

[History for DMN Decisions]: /user-guide/process-engine/decisions/history