# Filtering Message Template Variables

## Overview

When designing Message Templates in Welkin, you can define filter variables that dynamically display and manipulate data from Custom Data Types (CDTs). Filter variables work similarly to pivot tables or database queries, allowing you to extract specific subsets of data based on field values and display them in messages and assessment PDFs.

This functionality enables sophisticated communication that references only the most relevant data points, such as displaying medication names and dosages for a specific medication category, or showing only recent assessment responses that meet certain criteria.

## Key Concepts

* **Filter Variable** – A dynamic reference that extracts and displays specific data based on conditions
* **Pivot Table Analogy** – Similar to filtering rows/columns in a spreadsheet based on criteria
* **Custom Data Type (CDT)** – The data source for the filter (must contain multiple fields)
* **Filter Field** – The field used to determine which records to display
* **Display Field** – The field whose values are actually shown in the message

## Prerequisites

1. You have created a Message Template in Designer
2. You have CDTs with multiple related fields (e.g., medication names and dosages)
3. You understand basic Welkin CDT structure
4. Your Message Template is being used for patient communications

## Creating Filtered Variables

### Step 1: Access Message Template Configuration

1. Log into Designer
2. Click **Create Draft**
3. Navigate to **Message Template** in the left sidebar
4. Either:
   * Click **+ New** to create a new message template, OR
   * Click on an existing template to edit it

### Step 2: Open the Variable Selector

1. In the Message Template editor, locate the **Variable** button (usually above the message body)
2. Click **Variable** or the **{}** icon to open the variables drawer
3. The right sidebar displays available variables organized by type:
   * System Variables
   * Patient Variables
   * Custom Data Type Variables
   * **Custom Data Type Filter Variables** (what we're configuring)

### Step 3: Configure Filter Variables

In the variables drawer, locate the **"Custom Data Type Variable"** section (may be labeled as "Filtered Variables" or similar).

#### Setting Up a Filter

1. **Select the Source CDT** – Choose the Custom Data Type that contains the data you want to filter
2. **Select the Filter Field** – Choose which field will be used as the filtering criteria
3. **Specify the Filter Value** – Define what value(s) the filter field should match
4. **Select the Display Field** – Choose which field's values will actually be shown in the message

### Step 4: Copy the Generated Variable

Once configured:

1. The system generates a variable reference (often shown with special syntax like `{{cdt_name[filter_field=value].display_field}}`)
2. Click to copy this variable
3. Paste it into your message body where you want the filtered data to appear

## Practical Examples

### Example 1: Display Specific Medication Information

**Scenario:** Patient is on multiple medications; you want to show only blood pressure medication names and dosages in a message.

**Setup:**

* **Source CDT:** `medications`
* **Filter Field:** `medication_category`
* **Filter Value:** `"blood pressure"`
* **Display Field:** `medication_name` and `dosage`

**Generated Variable:** `{{medications[medication_category="blood pressure"].medication_name_dosage}}`

**Message Result:**

```
Here are your current blood pressure medications:
- Lisinopril 10mg daily
- Amlodipine 5mg daily
```

### Example 2: Show Recent Assessment Responses

**Scenario:** Show only the most recent depression screening responses in a follow-up message.

**Setup:**

* **Source CDT:** `depression_assessment_responses`
* **Filter Field:** `assessment_date`
* **Filter Value:** `last 7 days` or specific date
* **Display Field:** `question` and `patient_response`

**Generated Variable:** `{{depression_responses[recent=true].response_text}}`

**Message Result:**

```
Based on your recent screening, here are your responses:
Q1: Have you felt sad? - Yes, frequently
Q2: Loss of interest? - Sometimes
```

### Example 3: Filter by Clinical Category

**Scenario:** Show only critical vital signs that are out of normal range.

**Setup:**

* **Source CDT:** `vital_signs`
* **Filter Field:** `is_abnormal`
* **Filter Value:** `true`
* **Display Field:** `vital_name` and `value`

**Generated Variable:** `{{vital_signs[is_abnormal=true].display_name}}`

**Message Result:**

```
The following vital signs need attention:
- Blood Pressure: 155/95 mmHg (High)
- Blood Glucose: 245 mg/dL (Elevated)
```

## Using Filtered Variables in Messages

### In Patient Messages

1. Compose your message text
2. Reference the filtered variable where you want data to appear
3. Use formatting like lists or tables to organize multiple filtered results
4. Example:

```
Hello {{patient_first_name}},

Here are your {{medications[category="diabetes"].medication_name}} that you're taking for diabetes management:
- {{medications[category="diabetes"].display_name_and_dose}}

Please continue taking these as prescribed.
```

### In Assessment PDFs

Filtered variables can also be used in PDF templates (Word documents):

1. Create your PDF template in Word
2. Include filtered variable syntax using the same format
3. When PDF generates, variables are replaced with filtered data
4. Example in PDF:

```
Current Medications for {{current_condition}}:
{{medications[condition="{{current_condition}}"].full_medication_info}}
```

## Advanced Filtering Techniques

### Multiple Filter Conditions

Some systems support combining multiple filter criteria:

```
{{cdt[field1="value1" AND field2="value2"].display_field}}
```

This would show data where BOTH conditions are true.

### Complex Filter Logic

Depending on your Welkin version:

* **OR Logic:** Show data matching ANY condition
* **NOT Logic:** Show data that does NOT match a condition
* **Range Filtering:** Filter by numeric ranges (e.g., "score > 10")
* **Date Ranges:** Filter by date ranges (e.g., "past 30 days")

### Nested Display Fields

You can sometimes display multiple fields together:

```
{{medications[category="blood_pressure"].(name + " " + dosage + " " + frequency)}}
```

This would show all three fields concatenated.

## Best Practices

1. **Test Thoroughly** – Send test messages with filter variables to ensure correct data displays
2. **Use Clear Naming** – Name CDT fields clearly so filter intent is obvious
3. **Document Filters** – Add comments explaining what each filter does for team knowledge
4. **Avoid Over-Filtering** – Keep filters simple; complex logic may be prone to errors
5. **Regular Updates** – Review messages if CDT structure changes
6. **Consider Empty Results** – What happens if no data matches the filter? Add fallback text:

   ```
   {{medications[category="diabetes"].medication_name}}
   OR "No diabetes medications currently prescribed"
   ```
7. **Performance** – Very large CDT data sets with complex filters may slow message rendering

## Troubleshooting

### Variable Not Populating

**Problem:** Message shows the variable syntax instead of data

**Solutions:**

* Verify the filter field name matches exactly (case-sensitive)
* Confirm the filter value matches actual data in the CDT
* Check that the display field exists in the CDT
* Verify the CDT has data entries for that patient

### Incorrect Data Displaying

**Problem:** Filter shows wrong data or too much data

**Solutions:**

* Review the filter criteria – may need to be more specific
* Check CDT field values to ensure they match filter conditions
* Verify display field is the correct one
* Test with a different patient to isolate data issues

### Empty Results

**Problem:** No data displays even though data exists

**Solutions:**

* Check patient enrollment – may not have assessments in that CDT yet
* Verify filter field values match exactly (including capitalization)
* Confirm CDT is published and associated with the message
* Check date filters if using time-based filtering

## Related Topics

* [Filtering With Message Template Variables](/designer/documents-and-assessments/filtering-with-message-template-variables.md) – Detailed variable reference
* [Custom Data Types (CDT): Designer](/designer/custom-data-types/custom-data-types-cdt-designer.md) – Creating CDTs for filtering
* [Create PDFs from Forms & Assessments](/designer/documents-and-assessments/create-pdfs-from-forms-assessments.md) – Using variables in PDFs
* [Automations that Trigger Outbound Communications](/designer/automations/automations-that-trigger-outbound-communications.md) – Using messages in automations
* [How to Create an Assessment or Form Template](/designer/documents-and-assessments/how-to-create-an-assessment-or-form-template.md) – Assessment data sources


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.welkinhealth.com/designer/documents-and-assessments/filtering-message-template-variables.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.