Merge pull request #305 from CodeForPhilly/user-guide

Added custom check documentation

Author: Michael-Dratch

docs/user-docs/docs/custom-checks.md

@@ -1 +1,229 @@
-# Custom Checks
+# Custom Eligibility Checks
+
+## 1. What Are Custom Eligibility Checks?
+
+The BDT platform provides a library of **public eligibility checks** — prebuilt rule components that cover common eligibility criteria such as age thresholds, residency requirements, and income limits. For most screeners, combining these public checks is sufficient to express the required eligibility logic.
+
+However, if the public checks do not cover a requirement specific to your use case, BDT allows you to build your own reusable **custom eligibility checks**.
+
+A custom eligibility check works exactly like a public check within your screener:
+
+- It accepts one or more inputs from the screener form
+- It evaluates a defined condition
+- It returns an eligibility result (`True` or `False`)
+
+The key difference is that you define the logic yourself using **DMN (Decision Model and Notation)**, a low-code standard for expressing decision rules.
+
+Once created and published, your custom checks appear alongside public checks in the **Configure Benefit** page and can be reused across multiple screeners.
+
+---
+
+## 2. DMN and FEEL
+
+Custom check logic is defined using **DMN** with expressions written in **FEEL**. Neither requires traditional programming experience, but understanding their core concepts will help you build effective checks.
+
+### 2.1 What Is DMN?
+
+**Decision Model and Notation (DMN)** is an open standard for modeling and executing decision logic. It provides a visual, structured way to express rules that a system can evaluate automatically.
+
+In BDT, each custom check is backed by a DMN model that contains one or more **decision tables** organized into a decision tree.
+
+DMN models have two main building blocks:
+
+- **Input Data nodes** — represent values coming in from the form or from configured parameters
+- **Decision nodes** — represent rules that evaluate those inputs and produce an output
+
+### 2.2 What Is FEEL?
+
+**FEEL (Friendly Enough Expression Language)** is the expression language used inside DMN to write rule conditions and computed values.
+
+FEEL is designed to be readable and approachable. A few examples:
+
+| FEEL Expression                   | Meaning                  |
+| --------------------------------- | ------------------------ |
+| `age >= 65`                       | Age is 65 or older       |
+| `state = "California"`            | State equals California  |
+| `income < 2000`                   | Income is less than 2000 |
+| `date("2024-01-01")`              | A specific date literal  |
+| `age >= minAge and age <= maxAge` | Age falls within a range |
+
+FEEL supports arithmetic, comparisons, logical operators (`and`, `or`, `not`), date functions, string functions, and more.
+
+### 2.3 Decision Tables
+
+The most common way to express eligibility logic in DMN is a **decision table** — a structured grid where each row is a rule.
+
+Each rule specifies:
+
+- **Input conditions** — the values or ranges that must be true for this rule to apply
+- **Output** — the result returned when the rule matches
+
+BDT eligibility checks always return `true` (eligible), `false` (not eligible), or a value indicating insufficient information.
+
+**Example — Minimum Age Check**:
+
+| Age (Input) | Eligible (Output) |
+| ----------- | ----------------- |
+| `>= 65`     | `true`            |
+| `< 65`      | `false`           |
+
+**Example — Income and Household Size Check**:
+
+| Household Size (Input) | Annual Income (Input) | Eligible (Output) |
+| ---------------------- | --------------------- | ----------------- |
+| `1`                    | `<= 20000`            | `true`            |
+| `2`                    | `<= 27000`            | `true`            |
+| `any`                  | `> 50000`             | `false`           |
+
+**Identifying the result node**:
+
+When you create a custom check in BDT, you give it a name (for example, "Household Income Limit"). Your DMN model must contain a decision node with that exact same name. BDT uses this naming convention to identify which decision node represents the final eligibility result for the check. All other decision nodes in the model are treated as intermediate steps that feed into it.
+
+### 2.4 Further Reading
+
+For a deeper understanding of DMN and FEEL, refer to the official documentation:
+
+- [DMN Documentation (Drools)](https://docs.drools.org/latest/drools-docs/drools/DMN/index.html)
+- [FEEL Language Handbook](https://kiegroup.github.io/dmn-feel-handbook/#dmn-feel-handbook)
+- [Learn DMN in 15 Minutes](https://learn-dmn-in-15-minutes.com/)
+
+---
+
+## 3. Managing Custom Checks
+
+The **Eligibility Checks** view lists all of the custom checks you have created. You can access it from the BDT home screen by selecting the **Eligibility Checks** tab.
+
+From this view, you can:
+
+- View all of your custom checks
+- Create a new custom check
+- Open an existing check to edit or publish it
+
+> TODO: Add image of Eligibility Checks list view
+
+### Creating a New Check
+
+To create a new custom check, select **Create New Check**. You will be prompted to provide:
+
+- **Name** — a descriptive name for the check (e.g., "Household Income Limit")
+- **Module** — the category or group that this check belongs to (e.g., `housing`)
+- **Description** — a brief explanation of what the check evaluates
+
+Once created, the check opens in the **Custom Check Editor**, where you define its logic, configure its parameters, test it, and publish it.
+
+---
+
+## 4. The Custom Check Editor
+
+When you open a custom check, you are taken to the **Custom Check Editor**. This editor has four tabs that guide you through the process of building and publishing a check:
+
+- **Parameters** — define configurable inputs for your check
+- **DMN Definition** — build the decision logic using the visual DMN editor
+- **Testing** — run the check against sample inputs to verify it behaves correctly
+- **Publish** — publish a version of the check to make it available in your screeners
+
+> TODO: Add image of Custom Check Editor navigation tabs
+
+---
+
+### 4.1 Parameters
+
+The **Parameters** tab is where you define inputs that can be configured when adding your check to a benefit, rather than being supplied directly by the form.
+
+**What is a parameter?**
+
+Most eligibility checks involve a threshold or reference value — for example, a minimum age or an income limit. Rather than hardcoding that value in your DMN logic, you can expose it as a **parameter**. When you add the check to a benefit, you supply the specific value for that parameter. This makes the check reusable across multiple benefits with different thresholds.
+
+**Example**: A custom income check might expose a `maximumIncome` parameter. When configuring the check on a benefit for Program A, you set `maximumIncome` to 20000. For Program B, you set it to 35000. The same check logic serves both without modification.
+
+**Adding a parameter**:
+
+Select **Create New Parameter** and fill in the following fields:
+
+- **Key** — the internal identifier used in your DMN model to reference this parameter (e.g., `maximumIncome`)
+- **Label** — the human-readable name displayed when configuring the check on a benefit
+- **Type** — the data type: `string`, `number`, `boolean`, or `date`
+- **Required** — whether the parameter must be provided when the check is added to a benefit
+
+> TODO: Add image of Parameters tab and Parameter modal
+
+---
+
+### 4.2 DMN Definition
+
+The **DMN Definition** tab contains the visual DMN editor where you define the decision logic for your check.
+
+The editor provides a graphical canvas for building your DMN model. You can create and connect decision nodes, define input data sources, build decision tables, and organize decisions into a Decision Service.
+
+**Saving your work**:
+
+Select **Save Changes** to persist your DMN model. The save button turns yellow when there are unsaved changes, so you can tell at a glance whether your current edits have been saved.
+
+**Validating your DMN**:
+
+Select **Validate Current DMN** to check your model for structural or syntax errors. If validation issues are found, a summary of the errors is displayed. Resolve all validation errors before testing or publishing your check.
+
+> TODO: Add image of DMN Definition tab
+
+---
+
+### 4.3 Testing
+
+The **Testing** tab lets you run your check against sample input data to verify that it evaluates correctly before publishing.
+
+The screen is split into two panels:
+
+**Left panel — Test Inputs**:
+
+Enter a JSON object representing the form inputs you want to test with. Each key in the JSON should correspond to an input defined in your DMN model.
+
+Example:
+
+```json
+{
+  "age": 72,
+  "state": "California"
+}
+```
+
+**Right panel — Check Summary**:
+
+Displays information about the check being tested, including its configured parameters and their current values.
+
+**Running a test**:
+
+Select **Run Test** to evaluate the check against your input data. The result is displayed as:
+
+- **Eligible** (green) — the check returned `true`
+- **Ineligible** (red) — the check returned `false`
+- **Need more information** (yellow) — the check could not determine eligibility from the provided inputs
+
+Use the testing tab iteratively as you build your DMN logic to confirm each rule behaves as expected.
+
+> TODO: Add image of Testing tab with a sample result
+
+---
+
+### 4.4 Publish
+
+The **Publish** tab is where you publish your custom check to make it available in the **Configure Benefit** page of your screeners.
+
+Eligibility checks use semantic versioning. Each time you publish, a new version is created. Previously published versions are preserved and remain available.
+
+> Publishing creates a snapshot of your current DMN model. Subsequent changes to the DMN definition do not affect already-published versions. You must publish again to make new changes available.
+
+**To publish a check**:
+
+Select **Publish Check**. The new version will appear in the **Published Versions** list below, sorted from newest to oldest.
+
+**Published version details**:
+
+Each published version displays:
+
+- **Name** — the check name
+- **Version** — the semantic version number (e.g., `1.0.0`)
+- **Module** — the module identifier
+
+Once published, the check and its version will appear in the **Your Checks** section when adding eligibility checks to a benefit in any of your screeners.
+
+> TODO: Add image of Publish tab with published versions list

docs/user-docs/docs/index.md

@@ -2,16 +2,9 @@
 
 ## 1. What Is the Benefit Decision Toolkit?
 
-The **Benefit Decision Toolkit (BDT)** is a low-code platform for building and publishing custom benefit eligibility screeners to the web.
+Organizations that connect people to public benefits spend a lot of time helping individuals determine whether they qualify for specific programs. Building custom tools to support this work typically requires software development resources that many program teams do not have. The **Benefit Decision Toolkit (BDT)** addresses this by providing a low-code platform where organizations can build and publish eligibility screeners without writing code.
 
-Using BDT, organizations can quickly create screeners that help individuals determine whether they may qualify for specific benefits. The platform is designed to be simple, flexible, and accessible, enabling teams to:
-
-- Build eligibility screeners without extensive engineering support
-- Configure eligibility logic using a guided interface
-- Deploy screeners for public or internal use
-- Provide users with clear, immediate eligibility results
-
-BDT streamlines the process of translating policy rules into an interactive, user-friendly web experience.
+BDT provides low-code editors for defining eligibility logic and building a user-facing form. It handles connecting the two and publishing the result to a public URL, giving applicants a way to quickly determine whether they may qualify for a benefit.
 
 ---
 
@@ -23,28 +16,46 @@ An **eligibility screener** is a web-based form that:
 2. Evaluates that information against defined eligibility rules
 3. Displays eligibility results based on the evaluation
 
-Each screener consists of two primary components:
+Each screener has two primary components that work together:
+
+### 2.1 User Interface
+
+The user interface is the form that end users interact with. It collects the information needed to evaluate eligibility and displays the results after the form is submitted.
 
-### User Interface (Frontend)
+### 2.2 Eligibility Logic
 
-The user interface is the form that end users interact with. It:
+The eligibility logic defines how user inputs are evaluated. It applies the benefit eligibility rules and determines the final eligibility outcome for each benefit the screener covers.
+
+BDT allows you to configure both the user interface form and back-end eligibility logic in low-code editors and then publishes them together as a single, accessible URL.
+
+> TODO: Insert example screenshot of a published screener
+
+---
 
-- Collects required input data
-- Guides users through the screening questions
-- Displays eligibility results
+## 3. Key Concepts
 
-### Eligibility Logic (Backend)
+BDT organizes eligibility logic around three core building blocks. Understanding how they relate to each other will help you get oriented before working through the User Guide.
 
-The eligibility logic defines how user inputs are evaluated. It:
+### 3.1 Screeners
 
-- Applies benefit eligibility rules
-- Processes responses
-- Determines the final eligibility outcome
+A **Screener** is the top-level project in BDT. It represents the complete web experience — including the form and the eligibility logic — for one or more related benefits. When you publish a screener, it becomes available at a public URL.
 
-Together, these components allow organizations to convert benefit requirements into a structured, automated decision experience.
+### 3.2 Benefits
 
-> TODO: Insert example screenshot of a screener
+A **Benefit** is a named program that you want to screen applicants for (for example, "SNAP" or "Medicaid"). Each screener can contain one or more benefits, and each benefit is evaluated independently.
+
+A user is eligible for a benefit only if all of its eligibility rules evaluate to `True`.
+
+### 3.3 Eligibility Checks
+
+An **Eligibility Check** is a reusable rule component that evaluates one aspect of eligibility — for example, whether an applicant meets a minimum age threshold or falls within an income limit. Each benefit is composed of one or more eligibility checks.
+
+BDT provides a library of **public checks** covering common eligibility criteria. If the public checks do not meet your needs, you can also create **custom checks** using a built-in DMN decision editor.
+
+---
 
 ## Next Steps
 
-The [User Guide](user-guide.md) walks through how to create, configure, and publish a screener using BDT. It provides step-by-step instructions and practical guidance to help you begin building and deploying your own eligibility screeners.
+- The [User Guide](user-guide.md) walks through the full process of creating, configuring, and publishing a screener — from setting up benefits and eligibility logic to building the form and deploying to a public URL.
+
+- The [Custom Checks](custom-checks.md) guide covers how to build reusable custom eligibility checks when the public check library does not cover your use case.