Skip to content

Commit 01f7594

Browse files
Michael-DratchMichael-Dratch
committed
Added custom check documentation
1 parent fd14727 commit 01f7594

File tree

3 files changed

+393
-90
lines changed

3 files changed

+393
-90
lines changed

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

Lines changed: 229 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,229 @@
1-
# Custom Checks
1+
# Custom Eligibility Checks
2+
3+
## 1. What Are Custom Eligibility Checks?
4+
5+
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.
6+
7+
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**.
8+
9+
A custom eligibility check works exactly like a public check within your screener:
10+
11+
- It accepts one or more inputs from the screener form
12+
- It evaluates a defined condition
13+
- It returns an eligibility result (`True` or `False`)
14+
15+
The key difference is that you define the logic yourself using **DMN (Decision Model and Notation)**, a low-code standard for expressing decision rules.
16+
17+
Once created and published, your custom checks appear alongside public checks in the **Configure Benefit** page and can be reused across multiple screeners.
18+
19+
---
20+
21+
## 2. DMN and FEEL
22+
23+
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.
24+
25+
### 2.1 What Is DMN?
26+
27+
**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.
28+
29+
In BDT, each custom check is backed by a DMN model that contains one or more **decision tables** organized into a decision tree.
30+
31+
DMN models have two main building blocks:
32+
33+
- **Input Data nodes** — represent values coming in from the form or from configured parameters
34+
- **Decision nodes** — represent rules that evaluate those inputs and produce an output
35+
36+
### 2.2 What Is FEEL?
37+
38+
**FEEL (Friendly Enough Expression Language)** is the expression language used inside DMN to write rule conditions and computed values.
39+
40+
FEEL is designed to be readable and approachable. A few examples:
41+
42+
| FEEL Expression | Meaning |
43+
| --------------------------------- | ------------------------ |
44+
| `age >= 65` | Age is 65 or older |
45+
| `state = "California"` | State equals California |
46+
| `income < 2000` | Income is less than 2000 |
47+
| `date("2024-01-01")` | A specific date literal |
48+
| `age >= minAge and age <= maxAge` | Age falls within a range |
49+
50+
FEEL supports arithmetic, comparisons, logical operators (`and`, `or`, `not`), date functions, string functions, and more.
51+
52+
### 2.3 Decision Tables
53+
54+
The most common way to express eligibility logic in DMN is a **decision table** — a structured grid where each row is a rule.
55+
56+
Each rule specifies:
57+
58+
- **Input conditions** — the values or ranges that must be true for this rule to apply
59+
- **Output** — the result returned when the rule matches
60+
61+
BDT eligibility checks always return `true` (eligible), `false` (not eligible), or a value indicating insufficient information.
62+
63+
**Example — Minimum Age Check**:
64+
65+
| Age (Input) | Eligible (Output) |
66+
| ----------- | ----------------- |
67+
| `>= 65` | `true` |
68+
| `< 65` | `false` |
69+
70+
**Example — Income and Household Size Check**:
71+
72+
| Household Size (Input) | Annual Income (Input) | Eligible (Output) |
73+
| ---------------------- | --------------------- | ----------------- |
74+
| `1` | `<= 20000` | `true` |
75+
| `2` | `<= 27000` | `true` |
76+
| `any` | `> 50000` | `false` |
77+
78+
**Identifying the result node**:
79+
80+
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.
81+
82+
### 2.4 Further Reading
83+
84+
For a deeper understanding of DMN and FEEL, refer to the official documentation:
85+
86+
- [DMN Documentation (Drools)](https://docs.drools.org/latest/drools-docs/drools/DMN/index.html)
87+
- [FEEL Language Handbook](https://kiegroup.github.io/dmn-feel-handbook/#dmn-feel-handbook)
88+
- [Learn DMN in 15 Minutes](https://learn-dmn-in-15-minutes.com/)
89+
90+
---
91+
92+
## 3. Managing Custom Checks
93+
94+
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.
95+
96+
From this view, you can:
97+
98+
- View all of your custom checks
99+
- Create a new custom check
100+
- Open an existing check to edit or publish it
101+
102+
> TODO: Add image of Eligibility Checks list view
103+
104+
### Creating a New Check
105+
106+
To create a new custom check, select **Create New Check**. You will be prompted to provide:
107+
108+
- **Name** — a descriptive name for the check (e.g., "Household Income Limit")
109+
- **Module** — the category or group that this check belongs to (e.g., `housing`)
110+
- **Description** — a brief explanation of what the check evaluates
111+
112+
Once created, the check opens in the **Custom Check Editor**, where you define its logic, configure its parameters, test it, and publish it.
113+
114+
---
115+
116+
## 4. The Custom Check Editor
117+
118+
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:
119+
120+
- **Parameters** — define configurable inputs for your check
121+
- **DMN Definition** — build the decision logic using the visual DMN editor
122+
- **Testing** — run the check against sample inputs to verify it behaves correctly
123+
- **Publish** — publish a version of the check to make it available in your screeners
124+
125+
> TODO: Add image of Custom Check Editor navigation tabs
126+
127+
---
128+
129+
### 4.1 Parameters
130+
131+
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.
132+
133+
**What is a parameter?**
134+
135+
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.
136+
137+
**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.
138+
139+
**Adding a parameter**:
140+
141+
Select **Create New Parameter** and fill in the following fields:
142+
143+
- **Key** — the internal identifier used in your DMN model to reference this parameter (e.g., `maximumIncome`)
144+
- **Label** — the human-readable name displayed when configuring the check on a benefit
145+
- **Type** — the data type: `string`, `number`, `boolean`, or `date`
146+
- **Required** — whether the parameter must be provided when the check is added to a benefit
147+
148+
> TODO: Add image of Parameters tab and Parameter modal
149+
150+
---
151+
152+
### 4.2 DMN Definition
153+
154+
The **DMN Definition** tab contains the visual DMN editor where you define the decision logic for your check.
155+
156+
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.
157+
158+
**Saving your work**:
159+
160+
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.
161+
162+
**Validating your DMN**:
163+
164+
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.
165+
166+
> TODO: Add image of DMN Definition tab
167+
168+
---
169+
170+
### 4.3 Testing
171+
172+
The **Testing** tab lets you run your check against sample input data to verify that it evaluates correctly before publishing.
173+
174+
The screen is split into two panels:
175+
176+
**Left panel — Test Inputs**:
177+
178+
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.
179+
180+
Example:
181+
182+
```json
183+
{
184+
"age": 72,
185+
"state": "California"
186+
}
187+
```
188+
189+
**Right panel — Check Summary**:
190+
191+
Displays information about the check being tested, including its configured parameters and their current values.
192+
193+
**Running a test**:
194+
195+
Select **Run Test** to evaluate the check against your input data. The result is displayed as:
196+
197+
- **Eligible** (green) — the check returned `true`
198+
- **Ineligible** (red) — the check returned `false`
199+
- **Need more information** (yellow) — the check could not determine eligibility from the provided inputs
200+
201+
Use the testing tab iteratively as you build your DMN logic to confirm each rule behaves as expected.
202+
203+
> TODO: Add image of Testing tab with a sample result
204+
205+
---
206+
207+
### 4.4 Publish
208+
209+
The **Publish** tab is where you publish your custom check to make it available in the **Configure Benefit** page of your screeners.
210+
211+
Eligibility checks use semantic versioning. Each time you publish, a new version is created. Previously published versions are preserved and remain available.
212+
213+
> 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.
214+
215+
**To publish a check**:
216+
217+
Select **Publish Check**. The new version will appear in the **Published Versions** list below, sorted from newest to oldest.
218+
219+
**Published version details**:
220+
221+
Each published version displays:
222+
223+
- **Name** — the check name
224+
- **Version** — the semantic version number (e.g., `1.0.0`)
225+
- **Module** — the module identifier
226+
227+
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.
228+
229+
> TODO: Add image of Publish tab with published versions list

‎docs/user-docs/docs/index.md‎

Lines changed: 34 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,9 @@
22

33
## 1. What Is the Benefit Decision Toolkit?
44

5-
The **Benefit Decision Toolkit (BDT)** is a low-code platform for building and publishing custom benefit eligibility screeners to the web.
5+
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.
66

7-
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:
8-
9-
- Build eligibility screeners without extensive engineering support
10-
- Configure eligibility logic using a guided interface
11-
- Deploy screeners for public or internal use
12-
- Provide users with clear, immediate eligibility results
13-
14-
BDT streamlines the process of translating policy rules into an interactive, user-friendly web experience.
7+
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.
158

169
---
1710

@@ -23,28 +16,46 @@ An **eligibility screener** is a web-based form that:
2316
2. Evaluates that information against defined eligibility rules
2417
3. Displays eligibility results based on the evaluation
2518

26-
Each screener consists of two primary components:
19+
Each screener has two primary components that work together:
20+
21+
### 2.1 User Interface
22+
23+
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.
2724

28-
### User Interface (Frontend)
25+
### 2.2 Eligibility Logic
2926

30-
The user interface is the form that end users interact with. It:
27+
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.
28+
29+
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.
30+
31+
> TODO: Insert example screenshot of a published screener
32+
33+
---
3134

32-
- Collects required input data
33-
- Guides users through the screening questions
34-
- Displays eligibility results
35+
## 3. Key Concepts
3536

36-
### Eligibility Logic (Backend)
37+
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.
3738

38-
The eligibility logic defines how user inputs are evaluated. It:
39+
### 3.1 Screeners
3940

40-
- Applies benefit eligibility rules
41-
- Processes responses
42-
- Determines the final eligibility outcome
41+
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.
4342

44-
Together, these components allow organizations to convert benefit requirements into a structured, automated decision experience.
43+
### 3.2 Benefits
4544

46-
> TODO: Insert example screenshot of a screener
45+
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.
46+
47+
A user is eligible for a benefit only if all of its eligibility rules evaluate to `True`.
48+
49+
### 3.3 Eligibility Checks
50+
51+
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.
52+
53+
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.
54+
55+
---
4756

4857
## Next Steps
4958

50-
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.
59+
- 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.
60+
61+
- 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.

0 commit comments

Comments
 (0)