diff --git a/docs/user-docs/docs/custom-checks.md b/docs/user-docs/docs/custom-checks.md index 0f24d384..32edb235 100644 --- a/docs/user-docs/docs/custom-checks.md +++ b/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 diff --git a/docs/user-docs/docs/index.md b/docs/user-docs/docs/index.md index 676d7949..f677fdde 100644 --- a/docs/user-docs/docs/index.md +++ b/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. diff --git a/docs/user-docs/docs/user-guide.md b/docs/user-docs/docs/user-guide.md index d407f14e..298ce0c2 100644 --- a/docs/user-docs/docs/user-guide.md +++ b/docs/user-docs/docs/user-guide.md @@ -1,6 +1,6 @@ # User Guide -This section explains how to create, configure, test, and publish an eligibility screener using the Benefit Decision Toolkit (BDT). +This guide walks through how to create, configure, test, and publish an eligibility screener using the Benefit Decision Toolkit (BDT). --- @@ -10,11 +10,15 @@ After signing in, you will land on the **Screeners** view. This page displays al From here, you can: -- View existing screeners +- View all of your existing screeners - Open and edit a screener - Create a new screener project -To begin building a new screener, select **Create New Screener** and provide a descriptive name. The name should clearly reflect the benefit or set of benefits being screened. +**Creating a new screener**: + +Select **Create New Screener** and provide a name for your screener. The name should clearly reflect the benefit or set of benefits being screened (for example, "Philadelphia Senior Benefits" or "Housing Assistance Eligibility"). + +After the screener is created, you are automatically taken to the **Screener Dashboard**. > TODO: Add image of Screeners view @@ -22,23 +26,16 @@ To begin building a new screener, select **Create New Screener** and provide a d ## 2. The Screener Dashboard -When you open a screener project, you are taken to the **Screener Dashboard**. - -The Dashboard is the central workspace for your screener. From here, you can: - -- Define eligibility logic -- Build and edit the frontend form -- Test the screener -- Publish the screener +When you open a screener project, you are taken to the **Screener Dashboard** — the central workspace for building and managing your screener. -At the top of the page, the navigation bar contains four primary workflow tabs: +At the top of the page, the navigation bar contains four tabs representing the main stages of screener development: -- **Manage Benefits** -- **Form Editor** -- **Preview** -- **Publish** +- **Manage Benefits** — define the eligibility logic for each benefit your screener evaluates +- **Form Editor** — build the user-facing form that collects applicant information +- **Preview** — test the screener end-to-end before publishing +- **Publish** — deploy your screener to a public URL -These tabs represent the main stages of screener development. +Work through these tabs in order when building a screener for the first time. The eligibility logic you define in **Manage Benefits** informs what inputs the **Form Editor** needs to collect, and both must be complete before **Preview** and **Publish** are meaningful. > TODO: Add image of Screener Dashboard @@ -48,93 +45,160 @@ These tabs represent the main stages of screener development. The **Manage Benefits** tab is where you define the eligibility logic used by your screener. -In the BDT platform, a **Benefit** is a configured set of eligibility rules that evaluates whether a user qualifies for a specific program. +In BDT, a **Benefit** is a named configuration that evaluates whether a user qualifies for a specific program. When a user submits the screener form: -When a user submits information through the screener form: +1. BDT collects the user's inputs from the form. +2. Each configured Benefit evaluates those inputs against its eligibility rules. +3. Each Benefit returns an eligibility result. +4. The results are displayed to the user on the form's results screen. -1. The screener collects the user’s inputs. -2. BDT passes those inputs to each configured Benefit. -3. Each Benefit evaluates its eligibility rules. -4. The Benefit returns an eligibility result. -5. The result is displayed to the user on the front-end form. - -A single screener can evaluate eligibility for one or multiple benefits. Each benefit’s logic is configured independently within the **Manage Benefits** tab. - -This allows a single screener to assess users for multiple related programs while keeping the eligibility rules for each benefit separate and manageable. +A single screener can evaluate eligibility for one or multiple benefits. Each benefit's logic is defined independently, which allows a screener to assess users for several related programs while keeping the eligibility rules for each benefit separate and manageable. ### 3.1 Manage Benefits Overview -The **Manage Benefits** tab displays all benefits configured for your screener. - -From this page, you can: +The **Manage Benefits** tab displays all benefits configured for your screener as a list of cards. -- **Create** a new benefit -- **Edit** an existing benefit -- **Delete** a benefit +From this view, you can: -Selecting a benefit opens the **Configure Benefit** page, where you define or modify its eligibility rules. +- **Create** a new benefit by selecting **Create New Benefit** and providing a name and description +- **Edit** a benefit by selecting **Edit** on its card, which opens the **Configure Benefit** page +- **Remove** a benefit by selecting **Remove** on its card -> TODO: Add image of Configure Benefit page +> TODO: Add image of Manage Benefits view --- ## 4. Configuring a Benefit -The **Configure Benefit** page is where you define the rules that determine whether a user qualifies for a specific benefit. +The **Configure Benefit** page is where you define the rules that determine whether a user qualifies for a specific benefit. You access it by selecting **Edit** on any benefit card. Each benefit contains one or more **Eligibility Checks**. -> A user is considered **eligible for the benefit only if all eligibility checks evaluate to `True`.** +> A user is considered **eligible for the benefit only if every eligibility check evaluates to `True`.** ---- - -### What Is an Eligibility Check? +### 4.1 What Is an Eligibility Check? An **Eligibility Check** is a reusable rule component that: -- Accepts one or more user inputs (from your form) +- Accepts one or more inputs (from the screener form or from configured parameters) - Evaluates a defined condition - Returns a boolean result (`True` or `False`) -You configure each check by selecting a check type and setting its parameters. +By adding multiple eligibility checks to a benefit, you define the complete set of criteria a user must meet to qualify. + +**Example**: + +Suppose a benefit requires that applicants be at least 65 years old and live in the state of Pennsylvania. You could configure: + +- A **Minimum Age** check with a minimum age parameter of `65` +- A **State of Residence** check with a state parameter of `Pennsylvania` + +If **both** checks return `True`, the user is eligible for the benefit. If **either** check returns `False`, the user is not eligible. + +### 4.2 Adding Eligibility Checks + +The left side of the Configure Benefit page displays the list of available eligibility checks. Checks are organized into two categories: + +- **Public Checks** — prebuilt checks available to all BDT users +- **Your Checks** — custom checks that you have created and published + +Each row in the list shows the check name, a brief description, and its version. Select **Add** on any row to add that check to the benefit. + +Once added, the check appears as a card in the right panel under the benefit's configured checks. + +> TODO: Add image of Configure Benefit page showing the check list and selected checks panel + +### 4.3 Configuring Check Parameters + +Many eligibility checks have **parameters** — configurable values that control how the check evaluates eligibility. Parameters allow the same check logic to be reused across multiple benefits with different thresholds. + +**Example**: A **Household Income Limit** check might have a `maximumIncome` parameter. You set it to `20000` for one benefit and `35000` for another. The underlying rule is the same; only the threshold differs. + +To configure the parameters for an added check, click on its card in the right panel. A modal will open showing a form with all of that check's configurable parameters. + +Fill in the value for each parameter and select **Confirm** to save. Required parameters are marked with a red asterisk (`*`). + +> TODO: Add image of Configure Check modal -#### Example +### 4.4 Removing a Check -Suppose a benefit requires that applicants: +To remove an eligibility check from a benefit, select the **X** button in the top-right corner of that check's card in the right panel. -- Be at least 65 years old -- Live in the state of California +--- + +## 5. Building the Form (Form Editor) + +The **Form Editor** tab is where you build the user-facing form that collects the information needed to evaluate eligibility. + +The editor provides a visual drag-and-drop canvas powered by Form-JS. You can add, arrange, and configure form fields without writing any code. + +**Saving your work**: + +Select **Save** to persist your form. The save button turns yellow when there are unsaved changes, so you can tell at a glance whether your current edits have been saved. + +> TODO: Add image of Form Editor -You could configure: +### 5.1 Connecting Form Fields to Eligibility Checks -- A **Person Minimum Age** check with a minimum age of `65` -- A **State of Residence** check set to `California` +For the screener to evaluate eligibility correctly, the form must collect all of the inputs that the configured eligibility checks require. Each form field has a **key** that identifies the data it collects — this key must match the input name expected by the corresponding eligibility check. -If **both** checks return `True`, the user is eligible. -If **either** check returns `False`, the user is not eligible. +The **Validate Form Outputs** drawer (accessible via a button at the bottom-right of the editor) helps you verify that your form covers all required inputs. It shows: -By combining multiple eligibility checks, you define the complete eligibility criteria for a benefit. +- **Form Outputs** — a list of all fields currently defined in the form and the data they will collect +- **Missing Inputs** — inputs required by your eligibility checks that the form does not yet provide (shown in red) +- **Satisfied Inputs** — required inputs that are already covered by form fields (shown in green) + +Use this drawer to identify gaps between your form and your eligibility logic, and resolve any missing inputs before moving to the Preview step. + +> TODO: Add image of Validate Form Outputs drawer --- -## 5. Adding and Managing Eligibility Checks +## 6. Previewing Your Screener + +The **Preview** tab provides a live test environment where you can interact with your screener exactly as an end user would, and verify that the eligibility logic produces the correct results. + +The preview screen is divided into two sections: + +**Form section**: + +Displays your screener form as it will appear to end users. Fill in the fields and select **Submit** to run the eligibility evaluation. -On the Configure Benefit page, you will see a list of available eligibility checks. +**Results section**: -Checks are organized into two categories: +After submitting, the results section displays the outcome for each benefit: -- **Public Checks** – Prebuilt checks available to all BDT users -- **Your Checks** – Custom checks that you have created +- **Eligible** (green) — all eligibility checks for the benefit returned `True` +- **Ineligible** (red) — one or more eligibility checks returned `False` +- **Need more information** (yellow) — one or more checks could not determine eligibility from the inputs provided -To use a check: +Each benefit's result also shows a breakdown of how each individual eligibility check evaluated, including whether it passed, failed, or was unable to determine, and what parameter values were used. This detail is useful for debugging eligibility logic during development. -1. Select the check from the list -2. Click **Add** -3. Add values for each of its required configuration parameters +> Use the Preview tab iteratively as you build your screener to confirm that each benefit evaluates correctly across a range of test inputs. -Once added, the check appears in the benefit’s list of configured checks. +> TODO: Add image of Preview tab with a sample result -> TODO: Add image of check list -> TODO: Add image of check parameter configuration +--- + +## 7. Publishing Your Screener + +The **Publish** tab is where you deploy your screener to a publicly accessible URL that you can share with end users. + +**To publish your screener**: + +Select **Deploy Screener**. BDT will package your current form and eligibility logic and make them available at a public URL. The URL is displayed on the Publish tab after the first deployment. + +The Publish tab shows: + +- **Screener URL** — the public link where end users can access and submit the screener +- **Last Published Date** — the date and time of the most recent deployment + +> Deploying your screener publishes a snapshot of the current form and benefit configuration. Subsequent edits to the form or eligibility logic are not reflected at the public URL until you deploy again. + +If you update your screener after publishing, return to the **Publish** tab and select **Deploy Screener** again to push the updated version to the public URL. + +> TODO: Add image of Publish tab showing public URL + +--- -For information about creating reusable custom checks, see [Custom Checks](custom-checks.md). +For information about creating reusable custom eligibility checks, see [Custom Checks](custom-checks.md).