From 03183f40e45f7e34791e91caad40906649a54228 Mon Sep 17 00:00:00 2001 From: Jason Porter Date: Mon, 27 Jun 2022 14:38:13 -0600 Subject: [PATCH] Missing files for last commit These didn't get picked up, I forgot them in the last commit. Signed-off-by: Jason Porter --- .../dmn/assembly-kogito-using-dmn-models.adoc | 3832 +++++++++++++++++ 1 file changed, 3832 insertions(+) create mode 100644 src/test/resources/docs/issue-95/dmn/assembly-kogito-using-dmn-models.adoc diff --git a/src/test/resources/docs/issue-95/dmn/assembly-kogito-using-dmn-models.adoc b/src/test/resources/docs/issue-95/dmn/assembly-kogito-using-dmn-models.adoc new file mode 100644 index 0000000..8c236ea --- /dev/null +++ b/src/test/resources/docs/issue-95/dmn/assembly-kogito-using-dmn-models.adoc @@ -0,0 +1,3832 @@ +[id="assembly-kogito-using-dmn-models"] += Using DMN models in {PRODUCT} services + +ifdef::context[:parent-context: {context}] +:context: kogito-dmn-models + +[role="_abstract"] +As a developer of business decisions, you can use Decision Model and Notation (DMN) to model a decision service graphically. +The decision requirements of a DMN decision model are determined by a decision requirements graph (DRG) that is depicted in one or more decision requirements diagrams (DRDs). +A DRD can represent part or all of the overall DRG for the DMN model. +DRDs trace business decisions from start to finish, with each decision node using logic defined in DMN boxed expressions such as decision tables. + +{PRODUCT} provides design and runtime support for DMN 1.2 models at conformance level 3, and runtime-only support for DMN 1.1 and 1.3 models at conformance level 3. You can design your DMN models with the {PRODUCT} DMN modeler in VSCode or import existing DMN models into your {PRODUCT} projects for deployment and execution. +DMN 1.1 and 1.3 models are currently not supported in the {PRODUCT} DMN modeler. + +For more information about DMN, see the Object Management Group (OMG) https://www.omg.org/spec/DMN[Decision Model and Notation specification]. + +// tag::ref-decision-authoring-assets[] +[id="ref-decision-authoring-assets_{context}"] +== Decision-authoring assets in {PRODUCT} + +[role="_abstract"] +{PRODUCT} supports several assets that you can use to define business decisions for your decision service. +Each decision-authoring asset has different advantages, and you might prefer to use one or a combination of multiple assets depending on your goals and needs. + +The following table highlights the main decision-authoring assets supported in {PRODUCT} projects to help you decide or confirm the best method for defining decisions in your decision service. + +.Decision-authoring assets supported in {PRODUCT} +[cols="20%,40%,20%,20%",options="header"] +|=== +|Asset +|Highlights +|Authoring tools +|Documentation + +|Decision Model and Notation (DMN) models +a| +* Are decision models based on a notation standard defined by the Object Management Group (OMG) +* Use graphical decision requirements diagrams (DRDs) that represent part or all of the overall decision requirements graph (DRG) to trace business decision flows +* Use an XML schema that allows the DMN models to be shared between DMN-compliant platforms +* Support Friendly Enough Expression Language (FEEL) to define decision logic in DMN decision tables and other DMN boxed expressions +* Can be integrated efficiently with Business Process Model and Notation (BPMN) process models +* Are optimal for creating comprehensive, illustrative, and stable decision flows +|{PRODUCT} DMN modeler in VSCode or other DMN-compliant editor +|xref:con-dmn_kogito-dmn-models[] + +|DRL rules +a| +* Are individual rules that you define directly in `.drl` text files +* Provide the most flexibility for defining rules and other technicalities of rule behavior +* Are optimal for creating rules that require advanced DRL options, such as rule units +* Have strict syntax requirements for rules to be compiled properly +|Any integrated development environment (IDE) +|xref:con-drl_kogito-drl-rules[] + +|Spreadsheet decision tables +a| +* Are tabular sets of rules that you define in `.xls` or `.xlsx` spreadsheet files +* Support template keys and values for creating rule templates +* Are optimal for business environments that already rely on decision tables for rules +* Have strict syntax requirements for rules to be compiled properly when used in {PRODUCT} +|Spreadsheet editor +|xref:con-decision-tables_kogito-decision-tables[] +|=== +// end::ref-decision-authoring-assets[] + +[id="con-dmn_{context}"] +== Decision Model and Notation (DMN) + +[role="_abstract"] +Decision Model and Notation (DMN) is a standard established by the https://www.omg.org/[Object Management Group (OMG)] for describing and modeling operational decisions. +DMN defines an XML schema that enables DMN models to be shared between DMN-compliant platforms and across organizations so that business analysts and business rules developers can collaborate in designing and implementing DMN decision services. +The DMN standard is similar to and can be used together with the Business Process Model and Notation (BPMN) standard for designing and modeling business processes. + +For more information about the background and applications of DMN, see the OMG https://www.omg.org/spec/DMN[Decision Model and Notation specification]. + +[id="con-dmn-conformance-levels_{context}"] +=== DMN conformance levels + +[role="_abstract"] +The DMN specification defines three incremental levels of conformance in a software implementation. +A product that claims compliance at one level must also be compliant with any preceding levels. +For example, a conformance level 3 implementation must also include the supported components in conformance levels 1 and 2. For the formal definitions of each conformance level, see the OMG https://www.omg.org/spec/DMN[Decision Model and Notation specification]. + +The following list summarizes the three DMN conformance levels: + +Conformance level 1:: +A DMN conformance level 1 implementation supports decision requirement diagrams (DRDs), decision logic, and decision tables, but decision models are not executable. +Any language can be used to define the expressions, including natural, unstructured languages. + +Conformance level 2:: +A DMN conformance level 2 implementation includes the requirements in conformance level 1, and supports Simplified Friendly Enough Expression Language (S-FEEL) expressions and fully executable decision models. + +Conformance level 3:: +A DMN conformance level 3 implementation includes the requirements in conformance levels 1 and 2, and supports Friendly Enough Expression Language (FEEL) expressions, the full set of boxed expressions, and fully executable decision models. + +{PRODUCT} provides design and runtime support for DMN 1.2 models at conformance level 3, and runtime-only support for DMN 1.1 and 1.3 models at conformance level 3. You can design your DMN models with the {PRODUCT} DMN modeler in VSCode or import existing DMN models into your {PRODUCT} projects for deployment and execution. +DMN 1.1 and 1.3 models are currently not supported in the {PRODUCT} DMN modeler. + +[id="ref-dmn-drd-components-ref-{context}"] +=== DMN decision requirements diagram (DRD) components + +[role="_abstract"] +A decision requirements diagram (DRD) is a visual representation of your DMN model. +A DRD can represent part or all of the overall decision requirements graph (DRG) for the DMN model. +DRDs trace business decisions using decision nodes, business knowledge models, sources of business knowledge, input data, and decision services. + +The following table summarizes the components in a DRD: + +.DRD components +[cols="20%,20%,40%,20%" options="header"] +|=== +2+|Component +|Description +|Notation + +.5+|Elements +|Decision +|Node where one or more input elements determine an output based on defined decision logic. +a| +image::kogito/dmn/dmn-decision-node.png[] + +|Business knowledge model +|Reusable function with one or more decision elements. Decisions that have the same logic but depend on different sub-input data or sub-decisions use business knowledge models to determine which procedure to follow. +a| +image::kogito/dmn/dmn-bkm-node.png[] + +|Knowledge source +|External authorities, documents, committees, or policies that regulate a decision or business knowledge model. Knowledge sources are references to real-world factors rather than executable business rules. +a| +image::kogito/dmn/dmn-knowledge-source-node.png[] + +|Input data +|Information used in a decision node or a business knowledge model. Input data usually includes business-level concepts or objects relevant to the business, such as loan applicant data used in a lending strategy. +a| +image::kogito/dmn/dmn-input-data-node.png[] + +|Decision service +a|Top-level decision containing a set of reusable decisions published as a service for invocation. A decision service can be invoked from an external application or a BPMN business process. + +a| +image::kogito/dmn/dmn-decision-service-node.png[] + +.3+|Requirement connectors +|Information requirement +|Connection from an input data node or decision node to another decision node that requires the information. +a| +image::kogito/dmn/dmn-info-connector.png[] + +|Knowledge requirement +|Connection from a business knowledge model to a decision node or to another business knowledge model that invokes the decision logic. +a| +image::kogito/dmn/dmn-knowledge-connector.png[] + +|Authority requirement +|Connection from an input data node or a decision node to a dependent knowledge source or from a knowledge source to a decision node, business knowledge model, or another knowledge source. +a| +image::kogito/dmn/dmn-authority-connector.png[] + +.2+|Artifacts +|Text annotation +|Explanatory note associated with an input data node, decision node, business knowledge model, or knowledge source. +a| +image::kogito/dmn/dmn-annotation-node.png[] + +|Association +|Connection from an input data node, decision node, business knowledge model, or knowledge source to a text annotation. +a| +image::kogito/dmn/dmn-association-connector.png[] +|=== + +The following table summarizes the permitted connectors between DRD elements: + +.DRD connector rules +[cols="20%,20%,20%,40%" options="header"] +|=== +|Starts from +|Connects to +|Connection type +|Example + +|Decision +|Decision +|Information requirement +a| +image::kogito/dmn/dmn-decision-to-decision.png[] + +.2+|Business knowledge model +|Decision +.2+|Knowledge requirement +a| +image::kogito/dmn/dmn-bkm-to-decision.png[] + +|Business knowledge model +a| +image::kogito/dmn/dmn-bkm-to-bkm.png[] + +.2+a|Decision service + +|Decision +.2+|Knowledge requirement +a| +image::kogito/dmn/dmn-decision-service-to-decision.png[] + +|Business knowledge model +a| +image::kogito/dmn/dmn-decision-service-to-bkm.png[] + +.2+|Input data +|Decision +|Information requirement +a| +image::kogito/dmn/dmn-input-to-decision.png[] + +|Knowledge source +|Authority requirement +a| +image::kogito/dmn/dmn-input-to-knowledge-source.png[] + +.3+|Knowledge source +|Decision +.3+|Authority requirement +a| +image::kogito/dmn/dmn-knowledge-source-to-decision.png[] + +|Business knowledge model +a| +image::kogito/dmn/dmn-knowledge-source-to-bkm.png[] + +|Knowledge source +a| +image::kogito/dmn/dmn-knowledge-source-to-knowledge-source.png[] + +|Decision +.4+|Text annotation +.4+|Association +a| +image::kogito/dmn/dmn-decision-to-annotation.png[] + +|Business knowledge model +a| +image::kogito/dmn/dmn-bkm-to-annotation.png[] + +|Knowledge source +a| +image::kogito/dmn/dmn-knowledge-source-to-annotation.png[] + +|Input data +a| +image::kogito/dmn/dmn-input-to-annotation.png[] +|=== + +The following example DRD illustrates some of these DMN components in practice: + +.Example DRD: Loan prequalification +image::kogito/dmn/dmn-example-drd.png[] + +The following example DRD illustrates DMN components that are part of a reusable decision service: + +.Example DRD: Phone call handling as a decision service +image::kogito/dmn/dmn-example-drd3.png[width=90%] + +In a DMN decision service node, the decision nodes in the bottom segment incorporate input data from outside of the decision service to arrive at a final decision in the top segment of the decision service node. +The resulting top-level decisions from the decision service are then implemented in any subsequent decisions or business knowledge requirements of the DMN model. +You can reuse DMN decision services in other DMN models to apply the same decision logic with different input data and different outgoing connections. + +//// +.Advanced DRD example: Lending strategy +image::kogito/dmn/dmn-example-drd2.png[] +//// + +[id="con-dmn-feel_{context}"] +=== Rule expressions in FEEL + +[role="_abstract"] +Friendly Enough Expression Language (FEEL) is an expression language defined by the Object Management Group (OMG) DMN specification. +FEEL expressions define the logic of a decision in a DMN model. +FEEL is designed to facilitate both decision modeling and execution by assigning semantics to the decision model constructs. +FEEL expressions in decision requirements diagrams (DRDs) occupy table cells in boxed expressions for decision nodes and business knowledge models. + +For more information about FEEL in DMN, see the OMG https://www.omg.org/spec/DMN[Decision Model and Notation specification]. + +[id="ref-dmn-feel-data-types_{context}"] +==== Data types in FEEL + +[role="_abstract"] +Friendly Enough Expression Language (FEEL) supports the following data types: + +* Numbers +* Strings +* Boolean values +* Dates +* Time +* Date and time +* Days and time duration +* Years and months duration +* Functions +* Contexts +* Ranges (or intervals) +* Lists + +NOTE: The DMN specification currently does not provide an explicit way of declaring a variable as a `function`, `context`, `range`, or `list`, but {PRODUCT} extends the DMN built-in types to support variables of these types. + +The following list describes each data type: + +Numbers:: +Numbers in FEEL are based on the http://ieeexplore.ieee.org/document/4610935/[IEEE 754-2008] Decimal 128 format, with 34 digits of precision. +Internally, numbers are represented in Java as https://docs.oracle.com/javase/8/docs/api/java/math/BigDecimal.html[`BigDecimals`] with `MathContext DECIMAL128`. +FEEL supports only one number data type, so the same type is used to represent both integers and floating point numbers. ++ +-- +FEEL numbers use a dot (`.`) as a decimal separator. +FEEL does not support `-INF`, `+INF`, or `NaN`. +FEEL uses +`null` to represent invalid numbers. + +{PRODUCT} extends the DMN specification and supports additional number notations: + +* *Scientific:* You can use scientific notation with the suffix `e` or `E`. +For example, `1.2e3` is the same as writing the expression `1.2*10**3`, but is a literal instead of an expression. +* *Hexadecimal:* You can use hexadecimal numbers with the prefix `0x`. +For example, `0xff` is the same as the decimal number `255`. +Both uppercase and lowercase letters are supported. +For example, `0XFF` is the same as `0xff`. +* *Type suffixes:* You can use the type suffixes `f`, `F`, `d`, `D`, `l`, and `L`. +These suffixes are ignored. +-- + +Strings:: +Strings in FEEL are any sequence of characters delimited by double quotation marks. ++ +-- +.Example +---- +"John Doe" +---- +-- + +Boolean values:: +FEEL uses three-valued boolean logic, so a boolean logic expression may have values `true`, `false`, or `null`. + + +Dates:: +Date literals are not supported in FEEL, but you can use the built-in `date()` function to construct date values. +Date strings in FEEL follow the format defined in the https://www.w3.org/TR/xmlschema-2/#date[XML Schema Part 2: Datatypes] document. +The format is `"YYYY-MM-DD"` where `YYYY` is the year with four digits, `MM` is the number of the month with two digits, and `DD` is the number of the day. ++ +-- +Example: + +---- +date( "2017-06-23" ) +---- + +Date objects have time equal to `"00:00:00"`, which is midnight. +The dates are considered to be local, without a timezone. +-- + +Time:: +Time literals are not supported in FEEL, but you can use the built-in `time()` function to construct time values. +Time strings in FEEL follow the format defined in the https://www.w3.org/TR/xmlschema-2/#time[XML Schema Part 2: Datatypes] document. +The format is `"hh:mm:ss[.uuu][(+-)hh:mm]"` where `hh` is the hour of the day (from `00` to `23`), `mm` is the minutes in the hour, and `ss` is the number of seconds in the minute. +Optionally, the string may define the number of milliseconds (`uuu`) within the second and contain a positive (`+`) or negative (`-`) offset from UTC time to define its timezone. +Instead of using an offset, you can use the letter `z` to represent the UTC time, which is the same as an offset of `-00:00`. +If no offset is defined, the time is considered to be local. ++ +-- +Examples: + +---- +time( "04:25:12" ) +time( "14:10:00+02:00" ) +time( "22:35:40.345-05:00" ) +time( "15:00:30z" ) +---- + +Time values that define an offset or a timezone cannot be compared to local times that do not define an offset or a timezone. +-- + +Date and time:: +Date and time literals are not supported in FEEL, but you can use the built-in `date and time()` function to construct date and time values. +Date and time strings in FEEL follow the format defined in the https://www.w3.org/TR/xmlschema-2/#dateTime[XML Schema Part 2: Datatypes] document. +The format is `"T