The DMN engine interface exposes methodsfor parsing and evaluating DMN Decisions.

Parse Decisions

Decisions can be parsed from an InputStream or transformed from a DmnModelInstance.

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

  1. // create a default DMN engine
  2. DmnEngine dmnEngine = DmnEngineConfiguration
  3.   .createDefaultDmnEngineConfiguration()
  4.   .buildEngine();
  6. InputStream inputStream = ...
  8. // parse all decision from the input stream
  9. List<DmnDecision> decisions = dmnEngine.parseDecisions(inputStream);

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);

The Decision Key

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.     </decisionTable>
  12.   </decision>
  13. </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.

  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 only the decision with the key "second-decision"
  10. DmnDecision decision = dmnEngine.parseDecision("second-decision", inputStream);

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
  8. DmnDecision decision = drg.getDecision("decision");
  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.

Decision Tables only

It is possible to check if a parsed decision is implemented as decision table 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. if (decision.isDecisionTable()) {
  17.   // ...
  18. }

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.

  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 the DMN decision from the input stream
  10. DmnDecision decision = dmnEngine.parseDecision("decisionKey", inputStream);
  12. // create the input variables
  13. VariableMap variables = ...;
  15. // evaluate the decision
  16. result = dmnEngine.evaluateDecision(decision, variables);
  18. // or if the decision is implemented as decision table then you can also use
  19. result = dmnEngine.evaluateDecisionTable(decision, variables);

Pass Variables

To provide the input variables for a decision evaluation you can use aJava Map<String, Object>, resp. a VariableMap or a VariableContext.

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 VariableContext to support lazy-loading of variables.

Interpret the Decision Result

The evaluation of a DMN decision returns a DmnDecisionResult. If the decision is implemented as decision table 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.

Evaluate Decisions - 图1

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:

  1. DmnDecisionResult decisionResult = dmnEngine.evaluateDecision(decision, variables);
  3. // returns the first rule result
  4. DmnDecisionResultEntries ruleResult = decisionResult.getFirstResult();
  6. // returns first rule result
  7. // but asserts that only a single one exists
  8. decisionResult.getSingleResult();
  10. // collects only the entries for an output column
  11. decisionResult.collectEntries("desiredDish");
  13. // returns the first output entry
  14. ruleResult.getFirstEntry();
  16. // also returns the first output entry
  17. // but asserts that only a single one exists
  18. ruleResult.getSingleEntry();
  20. // shortcut to returns the single output entry of the single rule result
  21. // - combine getSingleResult() and getSingleEntry()
  22. decisionResult.getSingleEntry();

Note that the decision can also be evaluated using theevaluateDecisionTable() method if it is implemented as decision table. In this case, evaluation returns a DmnDecisionTableResult which is semantically equal and provides the same methods as aDmnDecisionResult.

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 decision requirements diagram shows that the Beverages decision requires the Dish decision (from the previous example).

Evaluate Decisions - 图3

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);
  5. List<String> beverages = decisionResult.collectEntries("beverages");

Hit Policy of Required Decisions

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 COLLECT hit policy with aggregator then the decision result (i.e. output value) is only the aggregated value.

In case of a hit policy with multiple matched rules (i.e., COLLECT without aggregator or RULE ORDER), the output variable is mapped to a list of output values, even if only one rule matched.

原文: https://docs.camunda.org/manual/7.9/user-guide/dmn-engine/evaluate-decisions/