Parse Decisions

Decisions can be parsed from an or transformed from a .

This example shows how to parse a decision from an input stream:

The next example uses the DMN Model API to first create aDmnModelInstance and then transform the decisions:

  1. // create a default DMN engine
  2. DmnEngine dmnEngine = DmnEngineConfiguration
  3.   .createDefaultDmnEngineConfiguration()
  4.   .buildEngine();
  6. // read a DMN model instance from a file
  7. DmnModelInstance dmnModelInstance = Dmn.readModelFromFile(...);
  9. // parse the decisions
  10. List<DmnDecision> decisions = dmnEngine.parseDecisions(dmnModelInstance);

A DMN XML file can contain multiple decisions - grouped by the decision requirements graph. To distinguish the decisions,every decision must have an id attribute.

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <definitions xmlns="http://www.omg.org/spec/DMN/20151101/dmn.xsd" id="definitions" name="definitions" namespace="http://camunda.org/schema/1.0/dmn">
  3.   <decision id="first-decision" name="First Decision">
  4.     <decisionTable>
  5.       <output id="output1"/>
  6.     </decisionTable>
  7.   </decision>
  8.   <decision id="second-decision" name="Second Decision">
  9.     <decisionTable>
  10.       <output id="output2"/>
  11.   </decision>
  12. </definitions>

The id of a decision in the XML is called key in the context of the DMNengine. To only parse a specific decision from a DMN file, you specify the decisionkey which corresponds to the id attribute in the XML file.

Parse Decision Requirements Graph

In addition to parsing all contained decisions of a decision requirements graph (DRG), the DMN engine can also parse the DRG itself from an InputStream or a DmnModelInstance.

  1. // parse the drg from an input stream
  2. DmnDecisionRequirementsGraph drg = dmnEngine.parseDecisionRequirementsGraph(inputStream);
  4. // get the keys of all containing decisions
  5. Set<String> decisionKeys = drg.getDecisionKeys();
  7. // get a containing decision by key
  10. // get all containing decisions
  11. Collection<DmnDecision> decisions = drg.getDecisions();

The DRG is represented in the XML by the definitions element. The id of the DRG in the XML is called key in the context of the DMN engine.

It is possible to check if a parsed decision is implemented as by using the method isDecisionTable().

  1. // create a default DMN engine
  2. DmnEngine dmnEngine = DmnEngineConfiguration
  3.   .createDefaultDmnEngineConfiguration()
  4.   .buildEngine();
  6. // read the DMN XML file as input stream
  7. InputStream inputStream = ...
  9. // parse all decision from the input stream
  10. List<DmnDecision> decisions = dmnEngine.parseDecisions(inputStream);
  12. // get the first decision
  13. DmnDecision decision = decisions.get(0);
  15. // do something if it is a decision table
  16.   // ...
  17. }

Evaluate Decisions

To evaluate (or “execute”) a decision, either pass an already transformed DmnDecision or use a DMN model instance or input stream in combination with a decision key.

As input to the evaluation, a set of input variables must be provided.

Pass Variables

The following example shows how to use a VariableMap.

  1. // create the input variables
  2. VariableMap variables = Variables.createVariables()
  3.   .putValue("x", "camunda")
  4.   .putValue("y", 2015);
  6. // evaluate the decision with the input variables
  7. result = dmnEngine.evaluateDecision(decision, variables);

Alternatively, a VariableContext can be used.Use the to support lazy-loading of variables.

The evaluation of a DMN decision returns a DmnDecisionResult. If the decision is implemented as then the result is a list of thematching decision rule results. These results represent a mapping from an output name to an output value.

If the decision is instead implemented as decision literal expression then the result is a listwhich contains only one entry. This entry represents the expression value and is mapped to the variable name.

Assume the following example of making a decision to select a dish.

The decision table returns the desiredDish as the output.

Assume that the decision table is executed with the following input variables:

  • season: “Spring”
  • guestCount: 14
    There is a matching rule in the table for the given inputs.The DmnDecisionResult thus consists of one DmnDecisionResultEntries which contains the key desiredDish.

To access the output value, get() method of DmnDecisionResultEntries is used:

  1. DmnDecisionResult decisionResult = dmnEngine.evaluateDecision(decision, variables);
  3. // the size will be 1
  4. int size = decisionResult.size();
  6. // get the matching rule
  7. DmnDecisionResultEntries ruleResult = decisionResult.get(0);
  9. // get output values by name
  10. Object result = ruleResult.get("desiredDish");

The result objects expose additional convenience methods:

Decisions with Required Decisions

If a decision has one or more required decisions, then the required decisions are evaluated first. The results of this evaluations are passed as input for the evaluation of the decision.

Assume the following example of making a decision to select beverages.

Evaluate Decisions - 图2

The following shows that the Beverages decision requires the Dish decision (from the previous example).

When the Beverages decision is evaluated then the DMN engine evaluates the Dish decision first.

Assume that the decision is evaluated with the following input variables:

  • season: “Spring”
  • guestCount: 14
  • guestsWithChildren: false
    With the above inputs, Dish decision table has one matching rule and generates the output value Stew that is mapped to the output variable desiredDish.

The output result of the Dish decision is used as input of the Beverages decision. That means that the input expression desiredDish of the Beverages decision returns the output value Stew of the Dish decision. In general, a decision can access the results (i.e., the output values) of required decisions by there output name.

As result, the Beverages decision has two matching rules and generates the output values Guiness and Water.

  1. DmnDecision decision = dmnEngine.parseDecision("beverages", inputStream);
  3. DmnDecisionResult decisionResult = dmnEngine.evaluateDecision(decision, variables);

The hit policy of a required decision can affect the result that is passed as input to the requiring decision. If the required decision has a hit policy with aggregator then the decision result (i.e. output value) is only the aggregated value.