Merge pull request InRule#56 from InRule/issue/1886-decision-docs

Add documentation for Decision Services

Author: Steven Kuhn

Authoring Samples/Decisions/README.md

@@ -0,0 +1,47 @@
+Decision Services
+====
+
+Decision Services is the newest member of InRule®'s Decision Platform. It provides an improved decision-centric model for authoring and executing rules, as well as an integration model that is standards-based that does not require deep knowledge of our SDK.
+
+A Decision in Decision Services is an entry point into rule exection. It consists of a set of inputs, rules that execute against those inputs, and a set of ouputs that reflect the result. Those inputs, outputs, and rules are author-defined, ultimately providing rule authors flexibility of shaping the input and output signature used during runtime execution.
+
+Once authored is complete, Decisions can be tested in irVerify and subsequently published to a Decision Runtime for remote execution via a RESTful API. The Decision Runtime provides an OpenAPI (formerly known as Swagger) document which is a programming language-agnostic description on how to execute the published Decisions, including each Decision's required input and output result.
+
+# Prerequisites
+
+Before you get started, you'll need to make sure you have the following:
+
+* For authoring and testing Decisions, [irAuthor 5.5.0](https://support.inrule.com/downloads.aspx) or greater.
+
+* For publishing and executing Decisions, access to a [Decision Runtime Service](#decision-runtime-service) using [Centralized Authentication](#centralized-authentication). Please contact [InRule Support](mailto:[email protected]) to request access.
+
+### Decision Runtime Service
+
+The Decision Runtime Service is responsible for storing and executing published Decisions. It also provides several OpenAPI documents based on the [OpenAPI specification](https://www.openapis.org/) (both [2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) and [3.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md)) as well as a [SwaggerUI](https://swagger.io/tools/swagger-ui/) interface. This allows integration with 3rd party tools like [Postman](https://www.getpostman.com/) or generating client code based on your published decisions.
+
+### Centralized Authentication
+
+Instead of relying on an irCatalog instance for authentication, InRule's hosted Decision Runtime Service integrates with its Centralized Authentication solution (running on the [Auth0](https://auth0.com/) platform). This authentication solution provides customers the ability to authenticate using external authentication providers including Azure Active Directory or any OpenID Connect compatible provider. 
+
+# Getting Started
+
+- [Authoring a Decision](author-decision.md)
+- [Testing a Decision](test-decision.md)
+- [Publishing a Decision](publish-decision.md)
+- [Executing a published Decision](execute-decision.md)
+
+# Integrations
+
+- [Power Automate (previously Microsoft Flow)](integrations/power-automate.md)
+
+# Notes
+
+InRule v5.5.0 includes additional classes in irSDK® to support Decisions. To make upgrading as painless as possible, the new data structures are persisted to files or irCatalog® in Attributes of the RuleApplicationDef.
+
+This removes the need to running a feature version upgrade on irCatalog to use these new features.
+
+Additionally the restriction on unique Entity Rule Set names has been removed, so long as they don't collide with existing Independent Rule Sets. This allows Rul eSets with the same names to exist under both Entities and Decisions.
+
+# Limitations
+
+* The majority of Rule Application authoring scenarios should inter-operate between versions 5.3.1-5.4.3 and 5.5.0 of irSDK/irAuthor/irCatalog. Howevever, there are [several edge cases](known-issues.md#mix-version-use-of-irsdkirauthorircatalog) that are not supported at this time.

Authoring Samples/Decisions/author-decision.md

@@ -0,0 +1,40 @@
+Authoring a Decision in irAuthor
+====
+
+# Adding a Decision
+
+A Decision can be added from the Decisions navigation panel.
+
+![Decision Navigation Panel](images/AuthorDecision-DecisionsNavPanel.png)
+
+Every new decision contains a single Rule Set named 'DecisionStart'. Any rules added to that Rule Set will execute automatically when the that Decision is executed.
+
+Additional explicit Rule Sets may be added to the Decision. These Rule Sets will execute only when called from the 'DecisionStart' Rule Set or from other Rule Sets within the same decision via the ExecuteRuleSet action. If an explicit Rule Set in a Decision is not explictly called via ExecuteRuleSet, then that Rule Set will not execute.
+
+Entity based Rule Sets can also be called from a Decision based rule set. This preserves the ability to author rules in the context of an Entity.
+
+# Editing a Decision
+
+When a Decision is selected in the Decisions navigation panel, the irAuthor content panel displays the Decision editor.
+
+![Decision Editor](images/AuthorDecision-DecisionEditor.png)
+
+## Inputs and Outputs
+
+Inputs and outputs may be added or removed using the ![Add](images/AuthorDecision-DecisionInputOutputAddButton.png) and ![Remove](images/AuthorDecision-DecisionInputOutputRemoveButton.png) buttons next to their data grids.
+
+When an input or output is added to the Decision, its 'Name' and 'Data Type' may be assigned. The Data Type may be any primitive data type inrule supports (Boolean, Data, DateTime, Decimal, Integer, Text), or an Entity previously authored in the Rule Application. An Entity input or output may be defined as an Entity Collection by checking the 'Is Collection' checkbox in the right-hand column.
+
+## Vocabulary
+
+Authors can create a vocabulary that allows them to make rules that read like regular English.  The vocabulary is a collection of English-language phrases, or more accurately, templates of English-language phrases, each connected to a value it will represent, or to an action it will take.
+
+Vocabulary may be authored by clicking the 'Create vocabulary' hyperlink at the bottom of the Decision editor. This allows business language vocabulary to be authored in the context of this Decision, which is available to Rules in any of its Rule Sets.
+
+# Rule Authoring
+
+Rules and actions may be added to Decision Rule Sets the same way that they may be added to Entity Rule Sets or Independent Rule Sets.
+
+All Decision Rule Sets are confined to explicit fire-mode. Any additional Rule Set added to the Decision may define parameters, however the 'DecisionStart' default Rule Set may not.
+
+![DecisionRules](images/AuthorDecision-DecisionRules.png)

Authoring Samples/Decisions/execute-decision.md

@@ -0,0 +1,130 @@
+Executing a Decision
+====
+
+# Overview
+
+Once a Decision has been published to a Decision Runtime, it is available for execution as a Decision Service.
+
+The base URL of the Decision Runtime will be the same URL used when the Decision was published.
+
+OpenAPI documents are available, which provide details of the URLs and JSON data structures for publishing and executing Decision Services.
+
+For example, if the base URL is:
+
+    https://myorg-decisions.inrulecloud.com/
+
+The OpenAPI 2.0 and 3.0 Specification documents for publishing would be:
+
+    https://myorg-decisions.inrulecloud.com/api/openapi_v2.0.json
+    https://myorg-decisions.inrulecloud.com/api/openapi_v3.0.json
+
+The OpenAPI 2.0 and 3.0 Specification documents for executing published Decision Services would be:
+
+    https://myorg-decisions.inrulecloud.com/api/decisions/openapi_v2.0.json
+    https://myorg-decisions.inrulecloud.com/api/decisions/openapi_v3.0.json
+
+These documents can be used by Swagger, Postman, or proxy generators for publishing and executing Decision Services.
+
+# Publication/Execution API via Swagger/OpenAPI Specification
+
+The Swagger test page would be accessed at the following URL:
+
+    https://myorg-decisions.inrulecloud.com/openapi/
+
+This explicitly lists all Decision Services available for execution, along with their associated schemas and example input/output JSON.
+
+![Execute Decision Swagger Operations](images/ExecuteDecision-SwaggerExecuteDecisions.png)
+
+The Decision Runtime uses OAuth 2.0 for authentication. Before using this interface, user credentials must be authenticated using the 'Authorize' button on the page.
+
+![Execute Decision Authorize Button](images/ExecuteDecision-AuthorizeButton.png)
+
+To authorize the Swagger page, a 'client_id' will be required before the authentication window appears. Please contact [InRule Support](mailto:[email protected])  for this client id.
+
+In addition to the 'Execution API', there is also a 'Publishing API' Swagger page that can be found in the drop-down menu at the top-right of the page:
+
+![Select a definition drop down](images/ExecuteDecision-PublishedDecisionsDropDown.png)
+    
+The following operations are possible:
+
+- List published Decisions
+- Publish a Decision
+- Get a Decision (Only confirms the name - Does not permit download of rule application)
+- Delete a Decision
+
+![Execute Decision Swagger Operations](images/ExecuteDecision-SwaggerOperations.png)
+
+*Note: This page also requires authorization.*
+
+# Execution API via Postman
+
+Postman offers an alternative mechanism for testing the Decision Services publication and execution API.
+
+## Import OpenAPI Configuration
+
+Using the Import functionality of the Postman application, the OpenAPI Specification document for executing Decision Services can be imported.
+
+![Execute Decision Postman Import OpenAPI](images/ExecuteDecision-PostmanImportOpenAPI.png)
+
+Enable the 'Generate a Postman Collection' option:
+
+![Execute Decision Postman Import OpenAPI](images/ExecuteDecision-PostmanImportOptions.png)
+
+After importing the OpenAPI specification, the Decision Services will be available in the collections list:
+
+![Execute Decision Postman CollectionsI](images/ExecuteDecision-PostmanCollections.png)
+
+Double-clicking one of the Decisions will open the form for the POST request.
+
+## Authorization
+
+Before sending the request to execute the Decision Service, the authorization header must be configured with a bearer token. This is retrieved from the OAuth 2.0 authentication service.
+
+Click the 'Authorization' tab and then click the 'Get New Access Token' button. Fill out the new token form using the following values:
+
+- Token Name: `[Any friendly name for the auth token]`
+- Grant Type: `Implicit`
+- Callback URL: `https://www.getpostman.com/oauth2/callback`
+- Auth URL: `https://auth.inrulecloud.com/authorize`
+- Client ID: `[Contact InRule Support for the Client ID to use with Postman]`
+- Scope: `[Leave empty]`
+- State: `[Leave empty]`
+- Client Authentication: `Send as Basic Auth header`
+
+![Execute Decision Postman New Token](images/ExecuteDecision-PostmanNewToken.png)
+
+Clicking the 'Request Token' button should retrieve a valid bearer token for use in the POST request's authorization header. Scroll down the dialog window containing the bearer token, and click the 'Use Token' button to apply it to the request.
+
+![Execute Decision Postman Bearer Token](images/ExecuteDecision-PostmanBearerToken.png)
+
+## Configuring Inputs
+
+Click the 'Body' tab on the request and it will display a sample JSON data structure illustrating the data types to use for each input.
+
+    {
+        "PresentValue": "<number>",
+        "InterestRate": "<number>",
+        "Periods": "<integer>"
+    }
+
+Change the values of the inputs to reflect the desired test values:
+
+    {
+        "PresentValue": 20000.00,
+        "InterestRate": 0.05,
+        "Periods": 5
+    }
+
+## Executing the Decision Service
+
+Once the authorization header is configured with the bearer token and the inputs are populated, simply click the 'Send' button to execute the Decision Service.
+
+![Execute Decision Postman Response](images/ExecuteDecision-PostmanResponse.png)
+
+The repsonse panel should contain the outputs of the Decision.
+
+If the response 'Status' says `200 OK` then the Decision Service was executed successfully.
+
+# Author-Publish-Execute Code Sample
+
+For an example application that programmatically authors, publishes, and executes a Decision Service, please see the [ExecuteDecisionSample](../../Developer%20Samples/ExecuteDecisionSample) developer sample.

Authoring Samples/Decisions/images/AuthorDecision-DecisionEditor.png

@@ -0,0 +1,31 @@
+Integrate with Power Automate (previously Microsoft Flow)
+====
+
+The Decision Runtime Service for Decisions Services provides an OpenAPI 2.0 document specific for Power Automate. That document can be found at a url similar to:
+
+`https://myorg-decisions.inrulecloud.com/api/decisions/powerautomate.json`
+
+With that document (either by using the URL or saving it locally) you can create a custom connector that can be used in Flows to execute Decisions.
+
+You can find information on how to create a customer connector for Power Automate from Microsoft [here](https://docs.microsoft.com/en-us/connectors/custom-connectors/define-openapi-definition#import-the-openapi-definition-for-microsoft-flow-and-powerapps).
+
+When you get to the step of "[Review authentication Type](https://docs.microsoft.com/en-us/connectors/custom-connectors/define-openapi-definition#import-the-openapi-definition-for-microsoft-flow-and-powerapps)", you can use the following settings (some will be populated automatically):
+
+* **Authentication Type**: `OAuth 2.0`
+
+* **OAuth 2.0**
+  * **Identity Provider**: `Generic Oauth 2`
+  * **Client id**: `CLIENT_ID_GOES_HERE`<br />
+    This will provided to you when granted access to a Decision Runtime Service environment. Please contact [InRule Support](mailto:[email protected]) to request access.
+  * **Client secret**: `CLIENT_SECRET_GOES_HERE`<br />
+    This will provided to you when granted access to a Decision Runtime Service environment. Please contact [InRule Support](mailto:[email protected]) to request access.
+  * **Authorization URL**: `https://auth.inrulecloud.com/authorize`<br />
+    The API authorization endpoint to authenticate with the service.
+  * **Token URL**: `https://auth.inrulecloud.com/oauth/token`<br />
+     The API endpoint to get the access token after the authorization has been done.
+  * **Refresh URL**: `https://auth.inrulecloud.com/oauth/token`<br />
+    The API endpoint to refresh the access token once it has expired. (This is the same as the Token URL)
+  * **Scope**: `offline`
+    Requires `offline` in order to provide a refresh token.
+
+Once those settings are in place, you should be able to create the connector and use that custom connector in your [logic apps](https://docs.microsoft.com/en-us/connectors/custom-connectors/use-custom-connector-logic-apps), [flows](https://docs.microsoft.com/en-us/connectors/custom-connectors/use-custom-connector-flow), or [PowerApps apps](https://docs.microsoft.com/en-us/connectors/custom-connectors/use-custom-connector-powerapps). Please refer to the [Microsoft documentation](https://docs.microsoft.com/en-us/connectors/custom-connectors/) for more information on custom connectors and Power Automate. 

Authoring Samples/Decisions/images/AuthorDecision-DecisionInputOutputAddButton.png

@@ -0,0 +1,38 @@
+Known Issues
+====
+
+# Mix Version Use of irSDK/irAuthor/irCatalog
+
+The majority of Rule Application authoring scenarios should inter-operate between versions 5.3.1-5.4.3 and 5.5.0 of irSDK/irAuthor/irCatalog. However, the following edge cases exist where unexpected behavior may occur:
+
+* Using v5.5.0 irAuthor/irSDK to check-in a Rule Application to a v5.5.0 irCatalog with duplicate RuleSet names under different Entities.
+
+  * Validation with v5.3.1 irAuthor/irSDK will fail with duplicate RuleSet error.
+
+* Using v5.5.0 irAuthor/irSDK to check-in a Rule Application to a v5.3.1 irCatalog with duplicate RuleSet names under different Entities. 
+
+  * Check-in will fail with duplicate RuleSet validation error.
+
+* Using v5.5.0 irAuthor/irSDK to check-in a Rule Application to a v5.5.0 irCatalog with a Decision Input/Output referencing Entity 'Entity1'.
+
+  * irAuthor/irSDK v5.3.1 checks-out the Rule Application, renames 'Entity1' to 'Entity2', and attempts to check-in the Rule Application. 
+
+  * Check-in will fail with error like "Unable to resolve Entity1 to an entity [Decision1.Input1]".
+
+* Using v5.5.0 irAuthor/irSDK to check-in a Rule Application to a v5.3.1 irCatalog with a Decision Input/Output referencing Entity 'Entity1'.
+
+  * irAuthor/irSDK v5.3.1 checks-out the Rule Application, renames 'Entity1' to 'Entity2', and checks-in the Rule Application successfully.
+
+  * irAuthor/irSDK v5.5.0 gets latest Rule Application from irCatalog successfully, but irAuthor/irSDK validation fails with error like "Unable to resolve Entity1 to an entity [Decision1.Input1]".
+
+* Using v5.5.0 irAuthor/irSDK to check-in a Rule Application to a v5.5.0 irCatalog with a Decision Input/Output referencing Entity 'Entity1' and a Decision rule referencing 'Field1' on that Entity.
+
+  * irAuthor/irSDK v5.3.1 checks-out the Rule Application, renames 'Field1' to 'Field2', and attempts to check-in the Rule Application.
+
+  * Check-in will fail with error like "Unable to resolve 'Input1.Field1' in context 'Decision1.DecisionStart.SetValue1' [--> Input1.Field1 <--] [Decision1.DecisionStart.SetValue1]"
+
+* Using v5.5.0 irAuthor/irSDK to check-in a Rule Application to a v5.3.1 irCatalog with a Decision Input/Output referencing Entity 'Entity1' and a Decision rule referencing 'Field1' on that Entity.
+
+  * irAuthor/irSDK v5.3.1 checks-out the Rule Application, renames 'Field1' to 'Field2', and checks-in the Rule Application.
+
+  * irAuthor/irSDK v5.5.0 gets latest Rule Application from irCatalog successfully, but irAuthor/irSDK validation fails with error like "Unable to resolve 'Input1.Field1' in context 'Decision1.DecisionStart.SetValue1' [--> Input1.Field1 <--] [Decision1.DecisionStart.SetValue1]".

Authoring Samples/Decisions/images/AuthorDecision-DecisionInputOutputRemoveButton.png

@@ -0,0 +1,26 @@
+Publishing a Decision
+====
+
+irAuthor contains a feature to publish Decisions so they are available for remote execution on the Decision Runtime. The 'Publish Decision' button can be found in the 'Home' tab.
+
+![Publish Decision Home Tab](images/PublishDecision-IrAuthorHomeTab.png)
+
+This opens a dialog window to enter the Decision Runtime URL, and select a Decision from the Rule Application to publish.
+
+![Publish Decision Dialog](images/PublishDecision-PublishDialog.png)
+
+The Decision Runtime URL must be a valid URL of a Decision Runtime. Any URLs used here will be saved in the drop-down menu for future use. The last used URL will always be at the top of the list.
+
+If a Decision or any of its Rule Sets or Rules are selected in the navigation panel, this will be the Decision selected by default in the 'Decision' drop-down menu, otherwise the first Decision will be selected.
+
+In order to successfully publish a Decision, the user must first be authenticated with the Decision Runtime. If irAuthor is not currently logged in to the centralized authentication, a login window will prompt for the user's email address and password.
+
+![Publish Decision Centralized Authentication](images/PublishDecision-CentralizedAuthentication.png)
+
+When attempting to publish a Decision whose name already exists on the Decision Runtime, a confirmation dialog window will ask whether the existing Decision should be overwritten.
+
+![Publish Decision Overwrite Existing Dialog](images/PublishDecision-OverwriteExistingDialog.png)
+
+When a Decision is published successfully, a dialog window will confirm this.
+
+![Publish Decision Success Dialog](images/PublishDecision-Success.png)