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 – Detailed variable reference

• Custom Data Types (CDT): Designer – Creating CDTs for filtering

• Create PDFs from Forms & Assessments – Using variables in PDFs

• Automations that Trigger Outbound Communications – Using messages in automations

• How to Create an Assessment or Form Template – Assessment data sources