BXMSDOC-3799: Getting started with decision services (apache#26) (apa…

…che#1429)

All reviews (SME, Peer, & QE) completed.

drools-docs/src/modules/ROOT/pages/DMN/dmn-con.adoc

@@ -1,6 +1,6 @@
 [id='dmn-con_{context}']
 = Decision Model and Notation (DMN)
 
-Decision Model and Notation (DMN) is a standard established by the 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 are unified 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.
+Decision Model and Notation (DMN) is a standard established by the 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].

drools-docs/src/modules/ROOT/pages/DMN/dmn-execution-con.adoc

@@ -1,7 +1,13 @@
 [id='dmn-execution-con']
 = DMN model execution
 
-You can create or import DMN files in your {PRODUCT} project using {CENTRAL} or package the DMN files as part of your project knowledge JAR (KJAR) file without {CENTRAL}. After you implement your DMN files in your {PRODUCT} project, you can execute the DMN decision service by deploying the KIE container that contains it to {KIE_SERVER} for remote access or by manipulating the KIE container directly as a dependency of the calling application. Other options for creating and deploying DMN knowledge packages are also available, and most are similar for all types of knowledge assets, such as DRL files or process definitions.
+You can create or import DMN files in your {PRODUCT} project using {CENTRAL} or package the DMN files as part of your project knowledge JAR (KJAR) file without {CENTRAL}. After you implement your DMN files in your {PRODUCT} project, you can execute the DMN decision service by deploying the KIE container that contains it to {KIE_SERVER} for remote access
+ifeval::["{context}" == "decision-service-getting-started"]
+and interacting with the container using the {KIE_SERVER} REST API.
+endif::[]
+ifeval::["{context}" == "dmn-models"]
+or by manipulating the KIE container directly as a dependency of the calling application. Other options for creating and deploying DMN knowledge packages are also available, and most are similar for all types of knowledge assets, such as DRL files or process definitions.
+endif::[]
 
 For information about including external DMN assets with your project packaging and deployment method, see
 ifdef::DM,PAM[]

drools-docs/src/modules/ROOT/pages/DMN/dmn-gs-assigning-custom-datatypes-proc.adoc

@@ -0,0 +1,21 @@
+[id='dmn-gs-assigning-custom-datatypes-proc']
+= Assigning custom data types to the DRD input and decision nodes
+
+After you create the DMN custom data types, assign them to the appropriate *DMN Input Data* and *DMN Decision* nodes in the traffic violations DRD.
+
+.Prerequisite
+* You have created the traffic violations DMN custom data types in {CENTRAL}.
+
+.Procedure
+. Click the *Model* tab on the DMN designer and click *Diagram properties* in the top-right corner of the DMN designer to expose the DRD properties.
+. In the DRD, select the *Driver* input data node and in the *Diagram properties* panel, set *Output data type* to `tDriver`.
+. Select the *Violation* input data node and set the *Output data type* to `tViolation`.
+. Select the *Fine* input data node and set the *Output data type* to `tFine`.
+. Select the *Should the driver be suspended?* decision node and set the following properties:
++
+* *Output data type*: `string`
+* *Question*: `Should the driver be suspended due to points on his driver license?`
+* *Allowed Answers*: `"Yes","No"`
+. Click *Save* to open the *Confirm Save* dialog box and click *Save* again.
+
+You have assigned the custom data types to your DRD's input and decision nodes.

drools-docs/src/modules/ROOT/pages/DMN/dmn-gs-creating-custom-datatypes-proc.adoc

@@ -0,0 +1,97 @@
+[id='dmn-gs-creating-custom-datatypes-proc']
+= Creating the traffic violations DMN custom data types
+
+DMN data types determine the structure of the data that you use within a table, column, or field in a DMN boxed expression for defining decision logic. You can use default DMN data types (such as string, number, or boolean) or you can create custom data types to specify additional fields and constraints that you want to implement for the boxed expression values. Use the DMN designer's *Data Types* tab in {CENTRAL} to define the custom data types for the traffic violations project.
+
+.The custom data types tab
+image::dmn/dmn-custom-datatypes-tab.png[]
+
+Alternately, you can also access the *Data Types* tab from the *Diagram properties* tab on the right. From the *Diagram properties* tab, click *Manage* from *Output data types* under *Information item*.
+
+.Diagram properties tab
+image::dmn/dmn-diagram-properties-tab.png[]
+
+The following tables list the `Violation`, `Driver`, and `Fine` custom data types that you will create for this project.
+
+.Driver custom data types
+[cols="1,1", options="header"]
+|===
+|Name |Type
+
+|tDriver |Structure
+|Name |string
+|Age |number
+|State |string
+|City |string
+|Points |number
+|===
+
+.Violation custom data types
+[cols="1,1", options="header"]
+|===
+|Name |Type
+
+|tViolation |Structure
+|Code |string
+|Date |date
+|Type |string
+|Speed Limit |number
+|Actual Speed |number
+|===
+
+.Fine custom data types
+[cols="1,1", options="header"]
+|===
+|Name |Type
+
+|tFine |Structure
+|Amount |number
+|Points |number
+|===
+
+.Prerequisite
+* You have created the traffic violations DMN decision requirements diagram (DRDs) in {CENTRAL}.
+
+.Procedure
+. From the *Data Types* tab, click *Add*.
+. First, create the *tDriver* custom data type. Enter `tDriver` as the *Name* and select `Structure` as the *Type*. Click *Save* for each data type that you add.
++
+.The tDriver custom data type
+image::dmn/dmn-tDriver-custom-datatype.png[]
+. Next to the *tDriver* data type, click the three vertical dots, select *Insert nested field*, and add the following nested data types. Click *Save* for each data type that you add.
++
+* *Name* (string)
+* *Age* (number)
+* *State* (string)
+* *City* (string)
+* *Points* (number)
+
+. Next, create the *tViolation* data type. From the *Data Types* tab, click *Add*.
++
+.The tViolation custom data type
+image::dmn/dmn-tViolation-custom-datatype.png[]
+. Enter `tViolation` as the *Name* and select `Structure` as the *Type*. Click *Save* to save the data type.
+. Next to the *tViolation* data type, click the three vertical dots, select *Insert nested field*, and add the following nested data types. Click *Save* for each data type that you add.
++
+* *Code* (string)
+* *Date* (date)
+* *Type* (string)
+* *Speed Limit* (number)
+* *Actual Speed* (number)
+
+. For the nested `Type` data type that you created, click *Edit* -> *Constraints* -> *Enumeration* and add the following constraints. Click the check icon image:dmn/dmn-datatype-constraints-tickmark.png[] to save each enumeration constraint that you add.
++
+* `"speed"`
+* `"parking"`
+* `"Driving under the influence?"`
+
+. Finally, create the *tFine* data type. From the *Data Types* tab, click *Add*.
++
+.The tFine custom data type
+image::dmn/dmn-tFine-custom-datatype.png[]
+. Enter `tFine` as the *Name* and select `Structure` as the *Type*. Click *Save* to save the data type.
+. Next to the *tFine* data type, click the three vertical dots, select *Insert nested field*, and add the following nested data types. Click *Save* for each data type that you add.
+* *Amount* (number)
+* *Points* (number)
+
+. Once all the three custom data types are created, click *Save* to open the *Confirm Save* dialog box and click *Save* again.

drools-docs/src/modules/ROOT/pages/DMN/dmn-gs-creating-drd-proc.adoc

@@ -0,0 +1,24 @@
+[id='dmn-gs-creating-drd-proc']
+= Creating the traffic violations DMN decision requirements diagram (DRD)
+
+A decision requirements diagram (DRD) is a visual representation of your DMN model. Use the  DMN designer in {CENTRAL} to design the DRD for the traffic violations project and to define the decision logic of the DRD components.
+
+.DRD for the Traffic Violations example
+image::dmn/dmn-traffic-violations-drd.png[]
+
+.Prerequisite
+* You have created the traffic violations project in {CENTRAL}.
+
+.Procedure
+. On the *traffic-violations* project's home screen, click *Add Asset* to open the *Add Asset* screen.
+. Click *DMN* to open the *Create new DMN* dialog.
+.. Enter `Traffic Violation` in the *Name* field.
+.. From the *Package* list, select `org.kie.example.traffic.traffic_violations`.
+.. Click *Ok* to open the DMN asset in the DMN designer.
+. In the DMN designer canvas, drag two input nodes to the canvas. Double-click the input nodes and rename them as `Driver` and `Violation`.
+. Drag a decision node to the canvas. Double-click and rename it as `Fine`.
+. Click the *Violation* input node and select the `Create DMN Information Requirement` option to connect to the `Fine` decision node.
+. Drag another decision node to the canvas and double-click and rename it as `Should the driver be suspended?`.
+. Click the *Driver* input node and select the  `Create DMN Information Requirement` option to connect to the `Should the driver be suspended?` decision node.
+. Click the *Fine* decision node and select the  `Create DMN Information Requirement` option to connect to the `Should the driver be suspended?` decision node.
+. Click *Save* to open the *Confirm Save* dialog box and click *Save* again.

drools-docs/src/modules/ROOT/pages/DMN/dmn-gs-defining-decision-logic-proc.adoc

@@ -0,0 +1,57 @@
+[id='dmn-gs-defining-decision-logic-proc']
+= Defining the traffic violations DMN decision logic
+
+To calculate the fine and to decide whether the driver is to be suspended or not, you can define the traffic violations DMN decision logic using a DMN decision table and context boxed expression.
+
+.Fine decision table
+image::dmn/dmn-gs-fine-decision-table.png[]
+
+.Should the driver be suspended? context boxed expression
+image::dmn/dmn-gs-context-table.png[]
+
+.Prerequisite
+* You have assigned the DMN custom data types to the appropriate decision and input nodes in the traffic violations DRD in {CENTRAL}.
+
+.Procedure
+. To calculate fine, in the DMN designer canvas, select the *Fine* decision node and click the *Edit* icon to open the DMN boxed expression designer.
+. Click *Select expression* -> *Decision Table*.
+. For the *Violation.Date*, *Violation.Code*, and *Violation.Speed Limit* parameter fields, right-click and select *Delete Input Clause* for each field.
+. Click the *Violation.Actual Speed* column header and enter the expression `Violation.Actual Speed - Violation.Speed Limit` in the *Name* field.
+. Right-click the *Fine* parameter field and select either `Insert Output Clause left` or `Insert Output Clause right`.
+. Click the *output-2* column sub-header, enter `Amount` in the *Name* field, and select `number` from the *Data Type* field.
+. Similarly, click the *output-1* column sub-header, enter `Points` in the *Name* field, and select `number` from the *Data Type* field.
+. Next, enter the following values in the first row of the decision table:
+* *Violation.Type*: `"speed"`
+* *Violation.Actual Speed - Violation.Speed Limit*: `[10..30]`
+* *Amount*: `500`
+* *Points*: `3`
++
+Right-click the first row and select `Insert rule below` to add another row.
+. Enter the following values in the second row of the decision table:
+* *Violation.Type*: `"speed"`
+* *Violation.Actual Speed - Violation.Speed Limit*: `>= 30`
+* *Amount*: `1000`
+* *Points*: `7`
++
+Right-click the second row and select `Insert rule below` to add another row.
+. Enter the following values in the third row of the decision table:
+* *Violation.Type*: `"parking"`
+* *Violation.Actual Speed - Violation.Speed Limit*: `-`
+* *Amount*: `100`
+* *Points*: `1`
++
+Right-click the third row and select `Insert rule below` to add another row.
+. Enter the following values in the fourth row of the decision table:
+* *Violation.Type*: `"driving under the influence"`
+* *Violation.Actual Speed - Violation.Speed Limit*: `-`
+* *Amount*: `1000`
+* *Points*: `5`
+. Click *Save* to open the *Confirm Save* dialog box and click *Save* again.
+. To define the driver suspension rule, return to the DMN designer canvas, select the *Should the driver be suspended?* decision node, and click the *Edit* icon to open the DMN boxed expression designer.
+. Click *Select expression* -> *Context*.
+. Click *ContextEntry-1*, enter `Total Points` as the *Name*, and select `number` as the *Data Type*.
+. Click the cell next to *Total Points*, select `Literal Expression` from the context menu, and enter `Driver.Points + Fine.Points` as the expression.
+. In the parameter cell below *Driver.Points + Fine.Points*, enter `if Total Points >= 20 "Yes" else "No"`.
+. Click *Save* to open the *Confirm Save* dialog box and click *Save* again.
++
+You have defined how to calculate the fine and the context for deciding when to suspend the driver. You can navigate to the *traffic_violations* project page and click *Build* to build the example project and address any errors noted in the *Alerts* panel.

drools-docs/src/modules/ROOT/pages/DMN/dmn-gs-new-project-creating-proc.adoc

@@ -0,0 +1,29 @@
+[id='dmn-gs-new-project-creating-proc']
+= Creating the traffic violations project
+
+For this example, create a new project called `traffic-violation`. A project is a container for assets such as data objects, DMN assets, and test scenarios.
+
+.Procedure
+. Log in to {CENTRAL}.
+. Go to *Menu* -> *Design* -> *Projects*.
++
+
+{PRODUCT} provides a default space called *MySpace*, as shown in the following image. You can use the default space to create and test example projects.
++
+
+.Default space
+image::getting-started/spaces-teams.png[]
+
+. Click *Add Project*.
+. Enter `traffic-violation` in the *Name* field.
+. Click *Show Advanced Options* to expand the GAV fields and enter the following values:
+* *Group ID*: `org.kie.example.traffic`
+* *Artifact ID*: `traffic-violation`
+* *Version*: `1.0.0`
+. Click *Add*.
++
+
+.Add Project window with expanded Advanced Options
+image::dmn/dmn-new-project-gs.png[]
++
+The *Assets* view of the project opens.

drools-docs/src/modules/ROOT/pages/DMN/dmn-gs-testing-test-scenario-proc.adoc

@@ -0,0 +1,84 @@
+[id='dmn-gs-testing-test-scenario-proc']
+= Testing the traffic violations using test scenarios
+
+Use the test scenarios designer in {CENTRAL} to test the DMN decision requirements diagrams (DRDs) and define decision logic for the traffic violations project.
+
+.Test scenario for the traffic violations example
+image::dmn/dmn-gs-traffic-violation-test-scenarios.png[]
+
+.Prerequisite
+* You have successfully build the traffic violations project in {CENTRAL}.
+
+.Procedure
+. On the *traffic-violation* project's home screen, click *Add Asset* to open the *Add Asset* screen.
+. Click *Test Scenario* to open the *Create new Test Scenario* dialog.
+.. Enter `Violation Scenarios` in the *Test Scenario* field.
+.. From the *Package* list, select `org.kie.example.traffic.traffic_violations`.
+.. Select `DMN` as the *Source type*.
+.. Click the *Choose DMN asset* text field and select the path to the DMN asset.
+.. Click *Ok* to open the *Violation Scenarios* test scenario in the *Test Scenarios* designer.
+. Under *Driver* column sub-header, right-click the *State*, *City*, *Age*, and *Name* value cells and select *Delete column* from the context menu options to remove them.
+. Under *Violation* column sub-header, right-click the *Date* and *Code* value cells and select *Delete column* to remove them.
+. Enter the following information in the first row of the test scenarios:
+* *Scenario description*: `Above speed limit: 10km/h and 30 km/h`
+* *Points* (under *Given* column header): `10`
+* *Type*: `"speed"`
+* *Speed Limit*: `100`
+* *Actual Speed*: `120`
+* *Points* (under *Expect* column header): `3`
+* *Amount*: `500`
+* *Should the driver be suspended?*: `"No"`
++
+Right-click the first row and select *Insert row below* to add another row.
+. Enter the following information in the second row of the test scenarios:
+* *Scenario description*: `Above speed limit: more than 30 km/h`
+* *Points* (under *Given* column header): `10`
+* *Type*: `"speed"`
+* *Speed Limit*: `100`
+* *Actual Speed*: `150`
+* *Points* (under *Expect* column header): `7`
+* *Amount*: `1000`
+* *Should the driver be suspended?*: `"No"`
++
+Right-click the second row and select *Insert row below* to add another row.
+. Enter the following information in the third row of the test scenarios:
+* *Scenario description*: `Parking violation`
+* *Points* (under *Given* column header): `10`
+* *Type*: `"parking"`
+* *Speed Limit*: `-`
+* *Actual Speed*: `-`
+* *Points* (under *Expect* column header): `1`
+* *Amount*: `100`
+* *Should the driver be suspended?*: `"No"`
++
+Right-click the third row and select *Insert row below* to add another row.
+. Enter the following information in the fourth row of the test scenarios:
+* *Scenario description*: `DUI violation`
+* *Points* (under *Given* column header): `10`
+* *Type*: `"driving under the influence"`
+* *Speed Limit*: leave blank
+* *Actual Speed*: leave blank
+* *Points* (under *Expect* column header): `5`
+* *Amount*: `1000`
+* *Should the driver be suspended?*: `"No"`
++
+Right-click the fourth row and select *Insert row below* to add another row.
+. Enter the following information in the fifth row of the test scenarios:
+* *Scenario description*: `Driver suspended`
+* *Points* (under *Given* column header): `15`
+* *Type*: `"speed"`
+* *Speed Limit*: `100`
+* *Actual Speed*: `140`
+* *Points* (under *Expect* column header): `7`
+* *Amount*: `1000`
+* *Should the driver be suspended?*: `"Yes"`
+. Click *Save* to open the *Confirm Save* dialog box and click *Save* again.
+. Click the play button to check whether the test scenarios pass or fail.
++
+.Test scenario execution result for the traffic violations example
+image::dmn/dmn-gs-test-scenarios-execution-results.png[]
++
+In case of failure, correct the errors and run the test scenarios again.
+
+//.DRD for the Traffic Violation example
+//image::dmn/dmn-traffic-violations-drd.png[]