# Welkin Health Knowledge Base
Official Welkin Health documentation for care teams, administrators, implementation teams, and developers.
Welkin Health is a configurable care management platform built for healthcare organizations managing complex patient populations. This knowledge base helps you understand the platform, get oriented, and complete your initial setup.
Start with the **Welcome** section to learn the basics. Then move to **Getting Started** to configure your organization and complete your first patient workflow.
***
## Welcome
Learn what Welkin Health is, who this documentation is for, and how to navigate the guide.
* [What is Welkin Health?](/welcome/what-is-welkin)
* [Who is this documentation for?](/welcome/who-is-this-for)
* [How to navigate this guide](/welcome/how-to-navigate)
* [Glossary of terms](/welcome/glossary)
***
## Getting Started
Set up your organization, invite users, review key concepts, and complete your first patient workflow.
* [Setting up your organization](/getting-started/setting-up-organization)
* [Inviting users and defining roles](/getting-started/inviting-users-and-roles)
* [Key concepts](/getting-started/key-concepts)
* [First patient workflow walkthrough](/getting-started/first-patient-workflow)
# Welcome
Welkin Health is a configurable care management platform built for healthcare organizations managing complex patient populations. This documentation covers everything you need to use, configure, and integrate with the Welkin platform.
Use the navigation on the left to browse by section, or start with the guides below.
* [What is Welkin Health?](/welcome/what-is-welkin)
* [Who is this documentation for?](/welcome/who-is-this-for)
* [How to navigate this guide](/welcome/how-to-navigate)
* [Glossary of terms](/welcome/glossary)
# What is Welkin Health?
Learn what Welkin Health is, the care management problems it solves, and the core workflows it supports for healthcare organizations.
Welkin Health is a **configurable care management platform** built for healthcare organizations that coordinate complex, ongoing care. It gives care teams a unified workspace to manage patients, communicate securely, track clinical outcomes, and automate repetitive workflows – all within a single platform.
***
## The problem Welkin solves
Managing care across a population of patients is operationally demanding. Care teams deal with fragmented tools, manual handoffs, inconsistent data collection, and time-consuming administrative work. This makes it hard to deliver the right care at the right time, and even harder to prove it's working.
Welkin brings structure to this complexity. It lets your organization define exactly how care should be delivered – the steps, the data, the timing, and the people involved – and then enforces that structure consistently across every patient.
***
## What you can do with Welkin
**Design the user experience** Using Designer, configure what care team members see – patient profile layouts, navigation, available forms, and workflow steps. Welkin adapts to your care model, not the other way around.
**Define your data structure** Create the data objects that capture the information your care model needs – custom data types (CDTs), assessment forms, field definitions, and structured questionnaires – all configured to match your specific workflows.
**Manage patients end-to-end** Maintain a complete record for each patient: demographics, program enrollment, care team assignment, encounter history, assessments, and documents – all in one place.
**Define and run care programs** Model your organization's care delivery as structured Programs made up of phases and milestones. Enroll patients and track their progress through the program.
**Coordinate care teams** Assign care workers to patients with specific roles. Every team member sees the information relevant to their role, and workloads are visible to managers.
**Collect structured clinical data** Build Assessments – forms, questionnaires, and screening tools – that capture the exact data points your care model requires. Add scoring, conditional logic, and question groups to handle complex workflows.
**Communicate securely** Reach patients via SMS, secure email (HIN, Paubox), and other channels directly from the platform. All communications are logged and searchable in the patient record.
**Automate workflows** Set up rules-based Automations that trigger actions – sending a message, assigning a task, enrolling in a program phase – based on patient data, calendar events, or form submissions.
**Schedule and track encounters** Manage appointments, care visits, and follow-ups through an integrated calendar with encounter tracking and status management.
**Integrate with your ecosystem** Connect Welkin to EHRs, external calendars (Outlook, Google), secure email providers, and any third-party system via the Welkin API and webhooks.
***
## Who uses Welkin?
Welkin is used by organizations delivering value-based care, specialty care management, behavioral health, chronic disease management, and other care programs that require ongoing, coordinated patient engagement.
Typical organizations using Welkin include:
* Health plans running care management programs
* Provider organizations with dedicated care coordination teams
* Digital health companies building care delivery on top of a flexible platform
* Specialty care practices managing high-complexity patients
***
## How Welkin is structured
Welkin is a multi-tenant SaaS platform. Your organization has its own isolated environment – called a **tenant** – within Welkin. All configuration (programs, assessments, user roles, automations) is specific to your tenant.
Within your tenant, data is scoped to a **region**, which determines where your data is stored and which Welkin infrastructure it runs on. Organizations with patients in multiple geographies may operate across multiple regions.
***
## Where to go next
* New to the platform? Start with [Key Concepts](broken://pages/qwJNfOR0sCpK7X6nvAXx) to learn the vocabulary.
* Setting up for the first time? Go to [Setting up your organization](broken://pages/0w6loqBIMhVX8z7NZn4r).
* Building an integration? Head to the [Developer Guide](https://github.com/welkincloud-io/welkin-docs/blob/master/kb/developer/README.md).
# Who is this documentation for?
Find the Welkin documentation paths most relevant to your role, including care teams, administrators, implementation teams, developers, and program leaders.
This guide serves multiple audiences. Use the table below to find the content most relevant to your role.
***
## Roles and recommended starting points
### Care Team Members
*Care managers, care coordinators, nurses, health coaches, and other staff who work directly with patients in the Care Portal.*
You spend most of your time in the Care Portal – viewing patient records, completing assessments, communicating, scheduling encounters, and tracking tasks.
**Start here:**
* [Key Concepts](broken://pages/qwJNfOR0sCpK7X6nvAXx) – understand Patients, Programs, Encounters, and Assessments
* [First Patient Workflow](broken://pages/Rh53mLr3hhyM33YVyMLc) – end-to-end walkthrough
***
### Organization Administrators
*System administrators, operations leads, and IT staff responsible for configuring and maintaining the Welkin environment.*
You configure the platform for your organization: managing users, setting security policies, and overseeing the organization's Welkin environment.
**Start here:**
* [Setting up your organization](broken://pages/0w6loqBIMhVX8z7NZn4r)
* [Inviting users and defining roles](broken://pages/53MPixpIxdU26dRk89OL)
***
### Implementation and Configuration Teams
*Teams responsible for building out care programs, assessments, automations, and workflows in Designer.*
You build the care delivery model in the Designer portal: programs, phases, assessments, CDTs, and automations.
**Start here:**
* [Setting up your organization](broken://pages/0w6loqBIMhVX8z7NZn4r)
* [Key Concepts](broken://pages/qwJNfOR0sCpK7X6nvAXx)
***
### Integration Developers
*Engineers and technical staff building integrations between Welkin and external systems.*
You use the Welkin API, webhooks, and API clients to move data between Welkin and your EHR, data warehouse, or other systems.
**Start here:**
* [Key Concepts](broken://pages/qwJNfOR0sCpK7X6nvAXx)
***
### Program Managers and Clinical Leaders
*Managers, clinical directors, and anyone responsible for program design, outcomes, and reporting.*
You design the care programs that run in Welkin and monitor their performance through reporting and analytics.
**Start here:**
* [Key Concepts](broken://pages/qwJNfOR0sCpK7X6nvAXx)
* [First Patient Workflow](broken://pages/Rh53mLr3hhyM33YVyMLc)
***
## How to get help
If you can't find what you're looking for in this documentation:
* **In-app help** – use the Help menu within the Welkin Care Portal
* **Your CSM** – contact your Welkin Customer Success representative for implementation guidance
> **Note:** This documentation covers Welkin's standard platform features. If your organization has custom configurations or workflows, some details may differ from what you see in your environment.
# How to navigate this guide
Learn how the Welkin documentation is organized, where to start based on your needs, and how to find setup, usage, and reference content quickly.
This documentation is organized to match the way different people use Welkin. Here is a map of the Welcome and Getting Started sections.
***
## Documentation structure
```
Welkin Health Documentation
│
├── Welcome ← You are here
│ ├── What is Welkin Health?
│ ├── Who is this documentation for?
│ ├── How to navigate this guide
│ └── Glossary of terms
│
└── Getting Started
├── Setting up your organization
├── Inviting users and defining roles
├── First patient workflow walkthrough
└── Key concepts
```
Use the left sidebar to navigate to other sections of the documentation.
***
## How pages are organized
Each section follows a consistent pattern:
1. **Overview** – what the section covers and when to use it
2. **Setup / Configuration** – how administrators configure the feature
3. **Usage** – how care team members use it day to day
4. **Reference** – detailed settings, field definitions, and edge cases
If you are a care team member, you can usually skip the configuration pages. If you are an administrator or implementation team member, you will want to read both.
***
## Finding what you need
**If you know the feature name**, use the left sidebar to navigate directly to it.
**If you are new to Welkin**, follow the [Getting Started](broken://pages/9GIwjnQmtkMP2nKMi5CZ) section in order – it walks you through everything from first setup to your first patient interaction.
**If you are looking up a term**, check the [Glossary](/welcome/glossary). Every platform-specific term used in this documentation is defined there.
***
## Conventions used in this guide
| Convention | Meaning |
| ---------------- | ------------------------------------------------------------- |
| **Bold text** | UI element names (buttons, fields, menu items) |
| `Monospace text` | API fields, configuration values, or code |
| > Blockquote | A tip, note, or important callout |
| ⚠️ Warning | Something to be careful about – data or workflow implications |
| 🔒 Admin only | This feature or setting requires Administrator access |
# Glossary of terms
Look up definitions for core Welkin platform terms used across the documentation, including care workflows, data structures, roles, and system concepts.
This glossary defines the terminology used throughout the Welkin Health platform and this documentation. Terms are listed alphabetically.
***
## A
**All-Region Access** A configuration option for Users and API Clients that grants access to data across all regions within a tenant, rather than being scoped to a single region. Typically used for reporting, integrations, and administrative tooling.
**Assessment** A structured data collection tool – similar to a form or questionnaire – used to gather clinical or operational information about a patient. Assessments are built in the Admin configuration and can include scored questions, conditional logic, and question groups. See Assessments.
**Assessment Score** A numeric value calculated from one or more scored questions in an Assessment. Welkin supports multiple scoring formulas, including scaled averages with lambda (λ) multipliers. Scores can be used in Automations and reporting.
**Audit Log** A system record of actions taken within Welkin – who did what, and when. Audit Logs are accessible to Administrators and are used for compliance and investigation purposes.
**Automation** A rules-based workflow that triggers one or more actions when a defined condition is met. Triggers can be based on patient data changes, calendar events, form submissions, time-based rules, and more. Actions can include sending a message, creating a task, updating a field, or enrolling a patient in a program phase. See Automations.
***
## C
**Care Portal** The primary web application used by care team members and administrators to manage patients, conduct encounters, communicate, and configure the platform.
**Care Program** See [Program](#p).
**Care Team** The group of users (Workers) assigned to care for a specific patient. Each Care Team member has a defined role that determines what they can see and do within the patient's record. See Care Team.
**Communication** Any message exchange between a care team member and a patient or external party through Welkin's messaging channels, including SMS, secure email (via HIN or Paubox), and in-app messaging.
**Condition** A logic rule used in Automations and Assessments to control behavior. For example, a condition might show a follow-up question only if a previous answer meets a certain threshold, or trigger an automation only if a patient's enrollment status matches a specific value.
***
## D
**Data Form** A configurable form used to capture structured, reusable data about a patient outside of an Assessment context. Data Forms are used for things like intake information, social determinants of health, and operational data points. See Data Forms.
**Data Type** A category of structured information in Welkin used as a source or target in Automations and Data Forms. Examples include Patient, Encounter, Assessment, and custom-defined types.
**Document** A generated or uploaded file associated with a patient record. Documents can be created from templates using patient data variables, or uploaded as PDFs. See Documents.
***
## E
**Encounter** A scheduled or completed interaction between a care team member and a patient – such as a care visit, phone call, or telehealth session. Encounters are managed through the Welkin Calendar and have statuses (e.g., Scheduled, Completed, Cancelled) that can be tracked and updated. See Calendar & Scheduling.
***
## F
**Field** A single data input within an Assessment, Data Form, or patient profile. Fields have types (text, number, date, dropdown, boolean, etc.) and can be configured with validation rules, scoring, and conditional visibility.
***
## H
**HIN (Health Information Network)** A secure messaging network integrated with Welkin for sending and receiving secure emails. Used as one of Welkin's secure email providers alongside Paubox.
***
## I
**Inbox** The communications hub within the Care Portal where care team members manage incoming and outgoing messages across all channels. The Inbox supports search across phone numbers, emails, patient names, and message content. See Communications.
***
## M
**Message Template** A reusable message with variable placeholders that is used in manual or automated communications. Variables (e.g., `{{PATIENT.firstName}}`, `{{ENCOUNTER.*.startDate}}`) are automatically populated with patient or encounter data when the message is sent. See Message Templates.
***
## O
**Organization** Your company or healthcare entity as represented in Welkin. Each organization has one or more Tenants and Regions within the Welkin platform.
***
## P
**Patient** The individual receiving care whose record is managed within Welkin. Also referred to as a "member" in some care model contexts. A patient record includes demographics, program enrollment, care team, encounters, assessments, communications, and documents.
**Paubox** A HIPAA-compliant secure email service integrated with Welkin. Used alongside HIN as a secure email provider for patient communications.
**Phase** A distinct stage within a Program. Programs are made up of one or more Phases through which patients progress. Each Phase can have its own configuration, tasks, and rules.
**Program** A structured care pathway or care plan that defines how a patient is managed over time. Programs consist of Phases and can include enrollment criteria, associated assessments, automations, and care team role requirements. See Programs and care phases.
***
## Q
**Question Group** A logical grouping of questions within an Assessment that can be repeated multiple times during completion (e.g., capturing the same set of data points for multiple medications). Question Groups support drag-and-drop reordering, conditional logic, and scoring. See Question Groups.
***
## R
**Region** A data jurisdiction within Welkin that determines where patient data is stored and processed. Organizations with patients in multiple geographies may operate across multiple regions. Users and API Clients can be scoped to one or more regions, or granted All-Region Access.
**Role** A named set of permissions assigned to a User within Welkin. Roles control which features, patients, and data a user can access and what actions they can take. Roles are defined by Administrators at the organization level. See [Inviting users and defining roles](broken://pages/53MPixpIxdU26dRk89OL).
***
## S
**Scoring** A configuration option in Assessments that assigns numeric values to question responses, which are then aggregated into an Assessment Score. Welkin supports multiple scoring formulas including Scaled Average. Questions without a scoring configuration can be excluded automatically.
**Secure Email** Encrypted email communication sent through integrated providers (HIN or Paubox) that meets HIPAA requirements for protected health information (PHI). Secure email can be sent manually or triggered via Automations.
***
## T
**Tenant** Your organization's isolated instance within the Welkin platform. All configuration, patient data, and user accounts within your tenant are separate from other organizations.
**Task** A to-do item assigned to a care team member within the context of a patient. Tasks can be created manually or automatically via Automations and are tracked on the patient record and in the care team member's work queue.
***
## U
**User** Any person with a login to your Welkin tenant. Users are assigned one or more Roles that govern their access. Users who work directly with patients are sometimes referred to as **Workers**. Administrators have access to the Admin configuration area.
***
## V
**Variable** A dynamic placeholder used in Message Templates and Documents that is replaced with actual patient or encounter data when rendered. Variables follow the format `{{OBJECT.field}}`, for example `{{PATIENT.firstName}}` or `{{ENCOUNTER.*.startDate}}`.
***
## W
**Webhook** An HTTP callback that Welkin sends to an external URL when a specified event occurs within the platform (e.g., an Assessment is completed, a patient is enrolled in a program). Used to trigger actions in external systems in real time. See [Webhooks](https://github.com/welkincloud-io/welkin-docs/blob/master/kb/designer/webhooks.md).
**Worker** A User who provides direct care to patients. Workers are assigned to patient Care Teams in specific roles. The term "Worker" is used in Welkin's configuration to refer to care-providing users as distinct from administrators.
# Getting Started
Follow the core Welkin setup path, from initial organization configuration and user access to key concepts and a first patient workflow.
This section walks you through everything you need to go from a new Welkin tenant to an operational care management environment. Follow the pages in order for the smoothest setup experience.
| Step | Page | Who it's for |
| ---- | ------------------------------------------------------------------------------ | ----------------- |
| 1 | [Setting up your organization](/getting-started/setting-up-organization) | Administrators |
| 2 | [Inviting users and defining roles](/getting-started/inviting-users-and-roles) | Administrators |
| 3 | [Key concepts](/getting-started/key-concepts) | Everyone |
| 4 | [First patient workflow walkthrough](/getting-started/first-patient-workflow) | Care team members |
> If your organization's Welkin environment is already configured and you're a new care team member, you can skip to [Key Concepts](/getting-started/key-concepts) and [First Patient Workflow](/getting-started/first-patient-workflow).
# Setting up your organization
Get a high-level setup path for a new Welkin environment, from roles and security to programs, assessments, automations, communications, and go-live testing.
This page gives a high-level overview of the steps to get your Welkin environment ready. Detailed instructions for each step live in their respective sections of this documentation, accessible from the left sidebar.
## Setup overview
Setting up Welkin happens across three portals:
* **Admin portal** – Manage users, roles, security policies, and organization-wide settings
* **Designer portal** – Configure care programs, assessments, automations, CDTs, and workflows
* **Care portal** – Where care teams and administrators work with patients day-to-day
A typical implementation follows this sequence:
1. **Configure user roles** – Define what each type of user can see and do before inviting anyone. See [Setting up Welkin Users](https://docs.welkinhealth.com/admin/users).
2. **Invite users** – Add your team members and assign them roles. See [Add, Delete, Modify Users](https://docs.welkinhealth.com/admin/add-new-users).
3. **Configure security policies** – Set attribute-based access control rules for your data. See [Security Policies](https://docs.welkinhealth.com/admin/security-policies).
4. **Build care programs in Designer** – Define the programs, phases, and care pathways your patients will follow. Use the left sidebar to navigate to the Designer section.
5. **Build assessments and forms** – Create the structured data collection tools your care teams will use. See [Create an Assessment or Form Template](https://docs.welkinhealth.com/designer/how-to-create-an-assessment-or-form-template).
6. **Configure automations** – Set up rules that trigger actions automatically based on patient data and events. See [How to Create Automations](https://docs.welkinhealth.com/designer/designer-how-to-create-automations).
7. **Enable communications** – Turn on SMS, email, and other communication channels. See [How to Turn On Communication Methods](https://docs.welkinhealth.com/admin/communication-center-how-to-turn-on-your-communication-methods).
8. **Test end-to-end** – Complete the [First Patient Workflow Walkthrough](/getting-started/first-patient-workflow) to verify your configuration before going live.
## Where to start
If you are brand new to Welkin, we recommend reading [Key Concepts](/getting-started/key-concepts) first to understand the platform's building blocks, then working through the setup steps above in order.
For hands-on implementation support, contact your Welkin Customer Success representative.
# Inviting users and defining roles
Understand how Welkin user access works, define role structures, and invite team members with the right permissions, regions, and portal access.
This page provides an overview of user management in Welkin. Detailed step-by-step instructions are in the Administration section (accessible from the left sidebar).
## How user access works
In Welkin, every person who logs in is a **User** assigned one or more **Roles**. Roles control:
* Which patients the user can view (only their assigned patients, or all patients)
* Which features and modules they can access
* What actions they can take (view, edit, or full access per feature)
* Which regions they can access
Getting roles right before inviting users is important – it avoids having to retroactively adjust permissions for everyone.
## Getting started with users
Follow these guides in order:
1. **Define your roles** – Before adding anyone, design the role structure for your organization. See [Setting up Welkin Users](https://docs.welkinhealth.com/admin/users).
2. **Add users** – Invite team members and assign them roles. See [Add, Delete, Modify Users](https://docs.welkinhealth.com/admin/add-new-users).
3. **Grant Designer access** – If any users need to configure the Designer portal, see [Granting Designer Portal Access](https://docs.welkinhealth.com/admin/designer-user-access).
4. **Assign seats and licenses** – See [Assigning Seats and Licenses](https://docs.welkinhealth.com/admin/assign-seats-and-licenses-to-new-users).
## Common role structure
Most organizations create at minimum:
| Role | Typical access |
| --------------- | ------------------------------------------ |
| Care Manager | Own patients only; full Care portal access |
| Care Supervisor | All patients in region; no Admin |
| Administrator | Full Admin configuration access |
Adjust these to match your care team structure. For detailed role configuration, see the Administration section in the left sidebar.
# First patient workflow walkthrough
Walk through a complete Welkin patient workflow, from record creation and program enrollment to assessments, encounters, communications, and timeline review.
This walkthrough takes you through the complete lifecycle of a patient in Welkin – from creating the record to completing a care interaction. It is designed to orient new care team members and to validate that a new configuration is working end-to-end.
> This guide assumes your organization's Welkin environment has already been configured with Programs, Assessments, and Roles. If not, see [Setting Up Your Organization](/getting-started/setting-up-organization) first.
***
## What you will do in this walkthrough
1. Create a patient record
2. Enroll the patient in a program
3. Assign a care team
4. Complete an assessment
5. Schedule an encounter
6. Send a message
7. Complete the encounter
8. Review the patient timeline
***
## Step 1: Create a patient record
1. From the Care Portal, click **Patients** in the left navigation
2. Click **+ New Patient**
3. Fill in the required fields: First Name, Last Name, Date of Birth, and contact information
4. Fill in any additional fields required by your organization's configuration
5. Click **Save**
The patient record opens automatically with an empty timeline.
***
## Step 2: Enroll the patient in a program
1. In the patient record, navigate to the **Programs** tab
2. Click **Enroll in Program**
3. Select the relevant program and starting Phase
4. Set the Enrollment Date and click **Enroll**
If Automations are configured to trigger on enrollment (e.g., sending a welcome message), they will fire at this point.
***
## Step 3: Assign a care team
1. In the patient record, navigate to the **Care Team** tab
2. Click **+ Add Care Team Member**
3. Search for and select a user
4. Select their Role on this patient's care team and click **Add**
***
## Step 4: Complete an assessment
1. In the patient record, navigate to the **Assessments** tab
2. Click **+ New Assessment**
3. Select the relevant assessment from the list
4. Complete all fields and click **Save** or **Submit**
The completed assessment appears in the patient timeline with a timestamp and score (if applicable).
***
## Step 5: Schedule an encounter
1. In the patient record, click **+ New Encounter** or go to the **Calendar**
2. Select the Encounter Type (Phone, In-Person, Telehealth)
3. Set the date, time, duration, and assigned care team member
4. Click **Save**
The encounter appears in the Calendar and on the patient's timeline with a "Scheduled" status.
***
## Step 6: Send a message
1. In the patient record, navigate to the **Communications** tab
2. Click **+ New Message**
3. Select the channel (SMS or Secure Email)
4. Type your message or select a Message Template
5. Click **Send**
***
## Step 7: Update encounter status
After the encounter takes place:
1. Navigate to the Calendar and find the encounter
2. Update the Status to **Completed**, **No Show**, or **Cancelled**
3. Add encounter notes and click **Save**
***
## Step 8: Review the patient timeline
Navigate to the patient record's **Timeline** tab to see a complete, chronological view of all activity: program enrollments, assessments, encounters, messages, tasks, and automation events.
***
## What to do next
Now that you have completed a full patient workflow, explore the detailed feature guides in the [Care Portal](https://docs.welkinhealth.com/care/) and [Administration](https://docs.welkinhealth.com/admin/) sections to go deeper on each area.
# Key concepts
Learn the core Welkin concepts that shape day-to-day workflows, including patients, programs, care teams, encounters, and assessments.
Before working in Welkin, it helps to understand the core building blocks of the platform. This page explains the five most important concepts and how they relate to each other.
***
## The big picture
Everything in Welkin revolves around a **Patient**. A patient is enrolled in a **Program**, cared for by a **Care Team**, seen in **Encounters**, and assessed through **Assessments**. Automations and communications tie these together.
```
Patient
├── enrolled in → Program (with Phases)
├── assigned to → Care Team (Workers in Roles)
├── scheduled for → Encounters (in the Calendar)
├── assessed via → Assessments (structured data collection)
└── reached via → Communications (SMS, secure email, inbox)
```
***
## 1. Patients
A **Patient** is the central record in Welkin. Every piece of activity – encounters, assessments, communications, documents – is associated with a patient.
A patient record contains:
* **Demographics** – name, date of birth, contact information, and custom fields
* **Program enrollment** – which care programs the patient is currently in and at what phase
* **Care Team** – the workers assigned to care for this patient
* **Encounter history** – all past and upcoming scheduled interactions
* **Assessments** – completed and in-progress data collection forms
* **Communications** – the full history of messages sent and received
* **Documents** – generated or uploaded files
* **Tasks** – to-do items assigned to care team members for this patient
Patients can be created manually by care team members or administrators, or created automatically via the API (for example, through an integration with an EHR or enrollment system).
***
## 2. Programs and Phases
A **Program** is a structured care pathway – the defined sequence of steps and activities that a patient goes through as part of their care.
Programs are made up of **Phases**, which represent distinct stages in the care journey. A patient moves through phases as they progress.
**Example – Chronic Disease Management Program:**
```
Phase 1: Intake & Assessment
→ Patient enrolled, demographics captured, initial assessment completed
Phase 2: Active Care
→ Weekly check-ins, ongoing assessments, care plan in place
Phase 3: Maintenance
→ Monthly check-ins, patient managing independently
Phase 4: Graduated
→ Care program completed
```
**Key things to know:**
* A patient can be enrolled in multiple programs simultaneously
* Enrollment in a phase can be triggered manually or automatically via Automations
* Each phase can have its own configuration, tasks, and associated assessments
* Admins define programs; care teams manage patient enrollment
***
## 3. Care Teams
A **Care Team** is the group of users assigned to care for a specific patient. Every patient has a care team, and every member of that team has a defined **Role** (e.g., Care Manager, Nurse, Health Coach, Supervisor).
The care team model serves two purposes:
1. **Access control** – only care team members can view the patient record when patient access is set to "own patients only"
2. **Coordination** – care team members know who else is involved in a patient's care and can coordinate accordingly
**Key things to know:**
* A patient can have multiple care team members, each with a different role
* A worker can be on the care teams of many patients (their caseload)
* Supervisors with broader access can see patients without being on their individual care teams
* Care team assignments can be managed manually or via Automations
***
## 4. Encounters
An **Encounter** is any scheduled or documented interaction between a care team member and a patient. Think of it as a record of a visit, call, or session.
Encounters are managed through the Welkin **Calendar** and have a lifecycle:
```
Scheduled → In Progress → Completed
↘ Cancelled / No Show
```
An encounter record captures:
* **Date, time, and duration** – with full timezone support
* **Type** – the kind of interaction (phone call, in-person visit, telehealth, etc.)
* **Status** – scheduled, completed, cancelled, no-show
* **Notes** – documentation from the encounter
* **Linked assessments** – assessments completed during the encounter
**Key things to know:**
* Encounters can be scheduled by any care team member with calendar access
* The calendar supports Outlook and Google Calendar integration for two-way sync
* Encounter status can be updated directly from the calendar view
* Automations can be triggered by encounter events (e.g., send a reminder before an encounter, send a follow-up after completion)
***
## 5. Assessments
An **Assessment** is a structured data collection tool – a form or questionnaire used to capture clinical or operational information about a patient at a point in time.
Assessments are built by administrators using the Assessment Builder and are then completed by care team members (or patients, if patient-facing functionality is enabled) during a patient interaction.
**Assessment features:**
* **Multiple field types** – text, number, date, dropdown, multi-select, boolean, and more
* **Scoring** – assign numeric values to responses; Welkin calculates a total or average score automatically
* **Conditional logic** – show or hide fields based on previous answers
* **Question Groups** – group related questions together; groups can be repeated multiple times within a single assessment completion (e.g., capturing the same fields for multiple medications)
* **N/A marking** – mark items as not applicable to exclude them from score calculations
* **History** – all completed assessments are saved to the patient record with timestamps
**Common uses:**
* Clinical screening tools (PHQ-9, GAD-7, HRA)
* Intake forms
* Care plan documentation
* Outcome measurement at regular intervals
* Social determinants of health screening
***
## How these concepts connect
Here's a realistic example of how a new patient flows through the platform:
1. **Patient created** – demographics entered, or imported via API from enrollment system
2. **Enrolled in program** – placed in the "Intake" phase of a care program
3. **Care team assigned** – a care manager is added to the patient's care team
4. **Intake assessment completed** – care manager fills out the screening form; a score is calculated
5. **Automation fires** – because the score is above a threshold, the patient is automatically moved to "Active Care" phase and a follow-up task is created
6. **Encounter scheduled** – care manager books a 30-minute call using the calendar
7. **Message sent** – automated appointment reminder sent via SMS the day before
8. **Encounter completed** – care manager marks the encounter as complete and documents notes
9. **Assessment completed** – during the encounter, a follow-up assessment is completed
10. **Program progresses** – after several months, the care manager manually advances the patient to "Maintenance" phase
This cycle repeats, with Automations handling the routine coordination so care teams can focus on the patients.
***
## Next step
Now that you understand the platform's building blocks, walk through the [First Patient Workflow](/getting-started/first-patient-workflow) to see them in action.
# Care Portal Overview
Overview of the Care Portal workspace, including navigation, core workflows, and key sections.
The Care Portal is the primary workspace for care team members in Welkin. It's where providers, care coordinators, and clinical staff manage patients, document clinical interactions, communicate, and track workflows — all in one place.
***
## Navigation
**Top bar** (available everywhere in Care):
| Icon | Function |
| ---------------- | ------------------------------------------------------- |
| Magnifying glass | Patient search — find by name, email, or phone |
| Bell | Notifications — system activity, task reminders, alerts |
| Question mark | Help |
| Shield/key | Switch to Admin portal |
| Notepad/pencil | Switch to Designer |
| User initials | Profile settings, role switching, log out |
**Left sidebar** provides access to the main sections described below.
***
## Home
The Home screen gives each care team member a personalized dashboard with upcoming encounters, tasks due today, recent patient activity, and quick-access widgets. Organizations can customize which widgets appear on the home screen.
→ [Home Screen](/care/getting-started/home-screen) · [Home Page Features & Functionality](/care/getting-started/home-page-features-functionality-highlights) · [New Homepage](/care/getting-started/new-homepage)
***
## Patients
The Patients section (also called **My Patients**) is where care team members find, create, and manage patient records. From here you can search for patients, create new records, view patient lists, and perform bulk actions.
Each patient has a **Patient Profile** — a full record containing demographics, care team assignments, program enrollment, encounters, assessments, documents, goals, tasks, and communication history.
→ [Patients](/care/patients/patients) · [Patient Profile](/care/patients/patient-profile) · [Patient Programs & Phases](/care/patients/care-programs-and-phases) · [Patient Care Teams](/care/patients/patient-care-teams)
***
## Calendar & Scheduling
The Calendar shows scheduled encounters across the care team. Care team members can view their own schedule or others', create and manage appointments, and set working hours and availability.
→ [Calendar](/care/calendar/calendar) · [Working Hours & Availability](/care/calendar/calendar-setting-up-working-hours)
***
## Encounters
Encounters represent clinical interactions between a care team member and a patient — a scheduled visit, a telehealth call, a phone check-in, or any structured interaction that generates a clinical record. Each encounter has a status (Scheduled, In Progress, Completed, Cancelled), associated assessments, notes, and a finalization workflow.
For full details on encounter statuses, workflows, and draft mode, see the dedicated pages below.
→ [Encounters Overview](/care/encounters/feature-overview-encounters) · [Encounters](/care/encounters/encounters) · [Create, Modify, Complete](/care/encounters/encounters-create-modify-complete)
***
## Tasks
Tasks are action items assigned to care team members, linked to a specific patient. They support clinical workflows by tracking things that need to be done — follow-up calls, form completions, approvals, or any ad-hoc action item. Tasks have statuses, due dates, assignees, and priority levels, and can be created manually or triggered automatically by workflows.
→ [Tasks](/care/tasks/tasks)
***
## Forms & Assessments
Care team members complete structured forms and assessments during or between encounters. Assessment results can feed into charts, trigger automations, and update goals. Forms are configured in Designer.
→ [Creating Forms and Assessments](/care/forms-and-assessments/creating-forms-and-assessments) · [Charts and Graphs](/care/forms-and-assessments/charts-and-graphs)
***
## Documents
The Documents section allows care teams to upload, organize, and review patient documents — clinical files, signed forms, lab results, and more.
→ [Document Management](/care/documents/documentmanagement) · [Upload Documents](/care/documents/upload-documents)
***
## Data Views
Data Views give care teams structured, tabular and AI-generated views of patient data drawn from Custom Data Types — distinct from the uploaded files in Documents. Use them to review vitals, lab values, medications, or AI-summarized data directly in the patient profile.
→ [Data Views](/care/data-views/data-views) · [AI Data View](/care/data-views/ai-widget)
***
## Communication
The Communication Center is the hub for all patient messaging. Care teams can send and receive SMS, email, in-app chat, and make calls — all tied to the patient record. Shared inboxes, message templates, and unrecognized communication handling are also available here.
→ [Communication Center](/care/communication/communication-center) · [Inbox](/care/communication/inbox) · [SMS](/care/communication/communication-center-sms) · [Email](/care/communication/email-functionality) · [Calls](/care/communication/communication-center-calls) · [Chat](/care/communication/chat) · [Fax](/care/communication/fax) · [Priority Cadence](/care/communication/priority-cadence)
***
## Goals
Goals allow care teams to set measurable clinical or behavioral objectives for patients and track progress over time. Goals can be linked to assessment scores for automatic progress updates.
→ [Goals](/care/patients/goals)
***
## Billing
The Billing section supports patient payment collection, invoice management, and recurring subscriptions — powered by Stripe. Billing managers can view invoices and subscriptions across all patients from a central billing tab.
→ [Payments & Invoices](/care/billing/payments-and-invoices)
***
## Reports & Insights
Reports and Insights give care teams and managers visibility into patient outcomes, encounter volumes, task completion rates, and other operational metrics.
→ [Insights](/care/getting-started/insights)
***
## Notifications
Welkin sends in-app and email notifications for upcoming encounters, task due dates, new patient messages, and automation-triggered events. Notification preferences are managed in your user profile.
→ [Notifications & Alerts](/care/getting-started/notifications-and-alerts) · [User Profile](/care/getting-started/user-profile)
***
## Roles & Access
What each user sees in the Care Portal depends on their **role**. Roles control which sections, patients, and actions are accessible. Roles are configured in Admin and assigned per user.
→ [Roles](/care/getting-started/roles) · [How to Create and Configure Roles](/care/getting-started/how-to-create-roles) · [Logging into Care](/care/getting-started/logging-in)
# Logging into Care
## Overview
The Welkin Care Portal is accessed via a web browser. You can log in using your organization's credentials, including SSO (Single Sign-On) if your organization has configured it.
## Logging In
### Standard Login
1. Navigate to your organization's Welkin Care Portal URL (provided by your administrator)
2. Enter your **Email Address** and **Password**
3. Click **Sign In**
### Single Sign-On (SSO)
If your organization uses SSO (Google, OneLogin, or another provider):
1. Navigate to your Care Portal URL
2. Click **Sign in with \[Your SSO Provider]**
3. You will be redirected to your identity provider to authenticate
4. Upon successful authentication, you will be returned to the Care Portal
### Two-Factor Authentication
If your organization has enabled two-factor authentication (2FA):
1. After entering your credentials, you will be prompted to enter a verification code
2. Check your authenticator app or the email/SMS sent to your registered contact
3. Enter the code within the time limit shown
4. Click **Verify**
## Forgotten Password
If you cannot log in:
1. Click **Forgot Password** on the login screen
2. Enter your email address
3. Check your email for a password reset link
4. Follow the link and set a new password
For admin-managed password resets, contact your Welkin administrator. See also [Reset Password](https://docs.welkinhealth.com/help-center/reset-password).
## Troubleshooting Login Issues
If you are unable to log in, try:
* Clearing your browser cache (see [Troubleshoot Browser Cache](/support/self-service/troubleshoot-browser-cache-chrome-safari))
* Confirming you are using the correct portal URL for your organization
* Contacting your administrator to confirm your account is active
# Roles
## Overview
Roles in Welkin define what a care team member can see and do within the Care Portal. Each user is assigned one or more roles by an administrator, and roles control access to patients, features, and functionality.
## What Roles Control
Roles determine:
* Which sections of the Care Portal a user can access (e.g., calendar, messages, documents)
* What actions a user can perform (e.g., create encounters, send messages, view assessments)
* Which patient records a user can see (optionally scoped by care team assignment or region)
* Whether a user can view sensitive data such as financial information or clinical notes
## Common Role Types
Organizations typically configure roles such as:
* **Care Coordinator** – manages patient enrollment, scheduling, and communication
* **Clinician / Provider** – conducts encounters, prescribes medications, completes clinical assessments
* **Care Manager** – oversees a panel of patients, monitors progress and outcomes
* **Supervisor / Manager** – reviews team workloads and performance, may have read-only access to all patients
* **Admin** – full access to configure the portal; typically not a patient-facing role
## How Roles Are Assigned
Roles are assigned by your Welkin Administrator in the Admin Portal. If you need a different role or additional access, contact your administrator.
## Seeing Your Role
To view your current role:
1. Click your profile icon in the top right corner
2. Select **User Profile** or **My Settings**
3. Your assigned role(s) are listed under your account details
For instructions on creating and configuring roles, see [How to Create and Configure Roles](/care/getting-started/how-to-create-roles).
***
## Related Topics
* [How to Create and Configure Roles](/care/getting-started/how-to-create-roles) – detailed role configuration guide
* [Security Policies](https://docs.welkinhealth.com/admin/security/security-policies) – attribute-based access control in Admin
* [Configuring Security Policies](https://docs.welkinhealth.com/designer/security/configuring-security-policies) – security policy setup in Designer
* [Patient Care Teams](/care/patients/patient-care-teams) – assigning team members to patients
# How to Create and Configure Roles
## Overview
Roles in Welkin are created and managed in the Admin Portal. Each role is a named permission set that controls what users assigned to that role can access and do.
## Creating a Role
1. Log in to the **Admin Portal**
2. Navigate to **Users → Roles**
3. Click **+ Add Role**
4. Enter a **Role Name** (e.g., "Care Coordinator", "Clinician")
5. Optionally add a **Description** to explain the role's purpose
6. Click **Save**
## Configuring Role Permissions
After creating a role, configure its permissions:
1. Click the role name to open the role editor
2. Under **Permissions**, toggle on the sections and features this role should have access to:
* **Patients** – view, create, edit, or delete patient records
* **Encounters** – view, create, complete, or delete encounters
* **Communications** – send/receive messages, calls, and SMS
* **Documents** – upload, view, or manage patient documents
* **Calendar** – view and edit calendar events
* **Assessments** – view and complete forms and assessments
* **Integrations** – access specific integrations such as eRx or DocuSign
3. Configure **Data Access** – optionally restrict the role to only see patients in their assigned care team or region
4. Click **Save**
## Assigning Roles to Users
1. Navigate to **Users** in the Admin Portal
2. Click the user to edit
3. Under **Role**, select the role(s) to assign
4. Save the user record
## Notes
* A user can have multiple roles; permissions are additive (the most permissive setting wins)
* Role changes take effect immediately when saved
* For Designer-level role controls (security policies), see [Security Policies (Admin)](https://docs.welkinhealth.com/admin/security/security-policies)
# User Profile
## Overview
The User Profile in the Welkin Care Portal contains your personal information as configured by your administrator. You can access your profile from the top-right corner of the Care Portal.
## Accessing Your Profile
1. Click your **profile icon** (initials or photo) in the top-right corner of the Care Portal
2. Select **My Profile** or **User Settings**
## Profile Information
Your profile includes:
* **Name** — your first and last name as it appears in the Care Portal
* **Email Address** — your login email (managed by your administrator)
* **Phone Number** — your direct line, used for internal communications
* **Role** — your assigned role(s); view-only (managed by administrators)
* **Profile Photo** — upload a photo that appears in patient-facing communications
## Notes
Notification preferences, password changes, and scheduling settings are managed by your administrator or configured in Welkin Designer — not through the Care Portal user profile. Contact your administrator if you need to update these settings.
# Notifications and Alerts
## Overview
Welkin's notification system keeps care team members informed of important events — including new patient messages, upcoming encounters, task due dates, and workflow triggers — without requiring constant manual checking.
## Types of Notifications
### In-App Notifications
Notifications appear as a badge on the bell icon in the top navigation bar. Click the bell to view a list of recent notifications. Each notification links directly to the relevant record or action.
### Email Notifications
Welkin can send email notifications to care team members for:
* New inbound patient messages
* Upcoming encounter reminders
* Task assignments or due dates
* Automation-triggered alerts
Email notifications are configured by your administrator in Welkin Designer.
### Automated Notifications
Automations configured in Designer can send notifications to care team members when specific conditions are met — for example, when a patient's assessment score changes or when a patient enters a new program phase. See [Automated Notifications](https://docs.welkinhealth.com/designer/automations/automated-notifications) for configuration details.
## Managing Notifications
To review or clear notifications:
1. Click the **bell icon** in the top navigation
2. Notifications are listed in reverse chronological order
3. Click a notification to navigate to the relevant record
4. Mark notifications as read individually or use **Mark All as Read**
## Notification Volume
If you are receiving too many notifications, contact your administrator to adjust automation-triggered notifications for your role in Designer.
# Home Screen
## Overview
The home screen is the first view care team members see upon logging in to the Welkin Care Portal. It provides a summary of your active workload, patients, and upcoming activity.
## Home Screen Layout
### Navigation Bar
The left-side navigation bar provides access to all major sections of the Care Portal:
* **Patients** – your patient list
* **Calendar** – your schedule and encounters
* **Messages** – your communication inbox
* **Tasks** – assigned tasks
* **Reports/Insights** – data views and metrics
### Main Content Area
The center of the home screen displays your patient dashboard, task list, and encounter schedule depending on how your organization has configured the home page.
### Search Bar
A global search bar at the top allows you to search for patients by name, phone number, email, or patient ID. Results display inline as you type.
### User Menu
Click your profile icon in the top right to access your user settings, notification preferences, and logout option.
## Navigating the Care Portal
Use the left navigation to move between sections. The breadcrumb trail at the top of each page shows where you are in the portal and allows quick back-navigation.
If your organization uses the new widget-based homepage, see [New Homepage](/care/getting-started/new-homepage) for details.
# Home Page Features & Functionality
## Overview
The Welkin Care Portal home page serves as the primary dashboard for care team members. It provides a centralized view of your patients, tasks, and upcoming activity so you can prioritize your work for the day.
## Key Home Page Features
### Patient List
The home page displays your assigned patients with quick access to their profiles, upcoming encounters, and outstanding tasks. You can filter by program, phase, or care team assignment.
### Task Panel
Active tasks assigned to you appear on the home page. Each task shows priority, due date, and the associated patient. Clicking a task takes you directly to the relevant patient record or encounter.
### Upcoming Encounters
A calendar-style view shows your scheduled encounters for the current day and upcoming days. Clicking an encounter opens the encounter detail where you can review notes, complete assessments, or start a call.
### Alerts and Notifications
The home page surfaces unread messages, flagged patient conditions, and workflow notifications from automations. Alerts are color-coded by urgency.
## Customizing the Home Page
Welkin's home screen supports a fully configurable widget and dashboard system. Administrators can build custom home screens that surface exactly the data care team members need — based on **any data point in the system**.
### Widget and Dashboard Builder
Using the New Homepage feature in Designer, administrators can:
* **Add and arrange widgets** — choose from patient lists, task queues, metrics summaries, calendar views, encounter counts, and more
* **Configure data sources** — each widget can be driven by any field, program, phase, or custom data type defined in your Welkin environment
* **Set role-based layouts** — different care roles (e.g., care managers, nurses, coordinators) can see tailored home screens with the widgets most relevant to their workflows
* **Control display logic** — apply filters, sorting, and grouping rules so each widget shows the right patients or records automatically
Because the home screen is 100% configurable, organizations can design dashboards that match their clinical workflows without any custom development.
For setup instructions and configuration options, see [New Homepage](/care/getting-started/new-homepage).
# New Homepage
## Overview
The New Homepage enhances daily operations by providing a personalized command center that transforms patient data into actionable insights. It consists of configurable **Widgets** organized into role-based **Dashboards**. Built on the OpenSearch analytics database, the Homepage allows for highly flexible querying while supporting real-time data updates.
> **Note:** The expression-builder interface enables business users to create queries within the Designer. However, users must have an understanding of XOR logic, Welkin entities and their relationships to construct valid queries. Ideally, users should be able to understand and validate the generated OpenSearch query displayed in the Source Code tab.
>
> Customers are responsible for building and testing Widgets. Assistance can be requested from the Welkin team via Professional Services hours if necessary (PSE).
For configuration steps, see:
* [New Homepage Setup (Admin)](https://docs.welkinhealth.com/admin) – how to activate the New Homepage per environment
* [New Homepage Configuration (Designer)](https://docs.welkinhealth.com/designer) – how to create Dashboards and Widgets
***
## Dashboards
A Dashboard is a set of widgets available on the New Homepage to users with a specific role.
When you log into the Care Portal, a drop-down list on the New Homepage displays the Dashboards available for your role. Selecting a Dashboard displays the list of Widgets added to it.
> **License note:** An environment is limited to **1 Dashboard** under the standard license. This limitation can be unlocked by enabling the **Homepage Plus** feature. Contact your CSM for pricing information.
***
## Widgets
A Widget is a set of rules by which information is selected and displayed. Each Widget queries patient or related entity data and presents it as a filterable, sortable list in the Care Portal.
### Entity Types
Widgets are built around one of the following entity types:
* Patient
* Patient Program
* Assessments
* Encounter
* CDT
* Notification
* Calendar event
The Patient is the parent entity; all others are child entities. Building a Widget from a child entity may introduce limitations (for example, filtering by patient fields is not possible when the widget is built from a child entity).
> **License note:** An environment is limited to **6 Widgets** under the standard license. This limitation can be unlocked by enabling the **Homepage Plus** feature. Contact your CSM for pricing information.
***
## Using Widgets in the Care Portal
Once Widgets are added to a Dashboard, the Care Portal displays a list of patients (or other entities) for whom the specified conditions are met.
Default sorting is applied to each Widget as configured, and column filters can be used to narrow results further.
Clicking on a patient or record in the Widget navigates directly to their profile or the relevant record.
***
## Date Expressions
Widgets support relative date expressions for condition fields. The `now` expression contains the current date and time in UTC.
**Relative dates without rounding:**
| Expression | Meaning |
| ---------- | ------------------- |
| `now` | Current time |
| `now-10m` | 10 minutes ago |
| `now+2h` | In 2 hours |
| `now-1d` | Same time yesterday |
| `now-1w` | 1 week ago |
| `now-1M` | 1 month ago |
| `now-1y` | A year ago |
**Relative dates with rounding:**
| Expression | Meaning |
| ---------- | ----------------------------------------- |
| `now/d` | Beginning of the current day (00:00:00) |
| `now/M` | Beginning of the current month (1st day) |
| `now/y` | Beginning of the current year (January 1) |
| `now-1d/d` | Beginning of yesterday (00:00:00) |
| `now-1w/w` | Beginning of last week (Monday) |
| `now-3M/M` | Start of the month 3 months ago |
> **Note:** When limiting results to "today", do not use the "between" expression. Use one expression for the beginning of the day and another for the end of the day.
***
## Current User Variable
In condition blocks for fields that refer to a username, you can use the `{{CURRENT_USER_NAME}}` variable to dynamically reference the logged-in user. Do not include extra spaces in the field containing this variable.
# Insights
## Overview
The Insights section of the Welkin Care Portal provides visibility into patient population metrics, outcome trends, and workflow performance. Access to Insights is controlled by role permissions configured in Designer.
## What Insights Include
Insights contains a set of system reports that cannot be customized. Available report sections include:
* **Patients**
* **Territories**
* **Assessments**
* **Calendar**
* **Encounters**
* **Tasks**
* **Export Data**
Each section has its own breakdown of analytics — some reports display as lists, others as pie, line, or bar graphs. Graphs are interactive and allow you to drill down further.
## Exporting Data
Where export is available within individual reports, a download icon appears on the right side of the report screen. This lets you export specific report data as a CSV file.
For a full data export, navigate to the **Export Data** section and click **Request to export all Insights data**. The system will generate a zipped CSV file folder. This may take a few moments depending on your database size.
## Notes
* Insights data reflects activity within your role's data access scope
* All reports in Insights are system reports and cannot be customized
* For more advanced analytics, your organization may use the Sisense integration; see [Sisense Change Requests](https://docs.welkinhealth.com/integrations/analytics-sisense/sisense-change-requests)
# Calendar
## Overview
The Calendar in the Welkin Care Portal provides a visual view of your scheduled encounters, appointments, and working hours. It helps care team members manage their time and coordinate with patients.
## Calendar Views
### Day View
Shows all encounters and appointments scheduled for a single day, displayed as time blocks. Hover over an event to see a summary; click to open the full encounter detail.
### Week View
Displays the full week with all scheduled events. Use this view to get an overview of your workload and identify open slots for new appointments.
### Month View
A high-level monthly overview of all encounters. Useful for scheduling planning and identifying busy or light periods.
## Navigating the Calendar
* Use the **arrow buttons** to move forward or backward in time
* Click **Today** to return to the current date
* Toggle between Day, Week, and Month views using the view selector
## Calendar Events
Events shown on the calendar include:
* **Encounters** – scheduled patient visits or calls
* **Blocked time** – non-patient time marked by you or set by an administrator
* **Availability windows** – your configured working hours
### Multi-day all-day events
All-day events that span more than one day appear as a continuous bar stretching across all the days they cover in the Week and Month views. A chevron indicator (» or «) marks where the event continues beyond the visible date range. In the Month view, multi-day events are pinned to the top of each cell and laid out in lanes to avoid overlap with single-day events.
## Syncing with External Calendars
If your organization has configured calendar synchronization, your Welkin calendar can sync with Google Calendar or Outlook. When events are imported from an external calendar, Welkin automatically carries over the event's timezone. If an external event has an unrecognized timezone, Welkin will fall back to the environment's default timezone rather than blocking the sync.
See [Calendar Synchronization App](https://docs.welkinhealth.com/integrations/calendar/calendar-synchronization-app) and [Working Hours and Encounter Availability](/care/calendar/calendar-setting-up-working-hours) for setup details.
## Creating Events
To schedule a new encounter from the calendar, navigate to a time slot and click to create an encounter directly.
***
## Related Topics
* [Working Hours and Encounter Availability](/care/calendar/calendar-setting-up-working-hours) – availability setup
* [Encounters](/care/encounters/encounters) – encounter management
* [Google Calendar Integration](https://docs.welkinhealth.com/integrations/calendar/google-calendar-integration) – external calendar sync
* [Calendar Synchronization App](https://docs.welkinhealth.com/integrations/calendar/calendar-synchronization-app) – multi-platform sync
{% embed url="" %}
# Working Hours and Encounter Availability
Each care team member configures their own availability in the **Calendar Settings** page. This controls when they can be booked for encounters and how their time appears in the calendar.
## Opening Working Hours settings
1. In the Care portal, navigate to **Calendar** from the left-hand menu.
2. Click the **gear icon** (⚙) near the top-right of the calendar to open the **Calendar Settings**.
3. Use the back arrow in the header to return to the calendar at any time.
The settings page has two tabs: **Working Hours** and **Sync with Calendar** (the Sync tab appears only if calendar synchronization is enabled for your organization).
***
## Working Hours tab
### Default Working Hours
Default Working Hours are your baseline availability — applied to all bookable encounter types unless overridden by a date exception.
* Toggle each **day of the week** on or off using the switch next to the day label.
* When a day is toggled on, set one or more **time slots** (start time and end time) for that day.
* Click the **+** button next to a time slot to add another time block for the same day.
* Click the **trash icon** to remove a time slot.
* Click **Add Availability Window** if no days are set yet to pre-fill a standard Monday–Friday schedule.
### Exceptions
Exceptions override your default schedule for specific dates or date ranges — useful for holidays, time off, or one-off schedule changes.
Click **Add custom hours** or **Add time off** to create an exception.
#### Custom hours exception
1. Select a **date range** (from date and to date).
2. The days within that range are shown. By default, all days in the range are active with the same hours.
3. Toggle: **Set different hours per day** to customize each day individually.
4. Click the day chips (Mon, Tue, etc.) to select which days in the range are working days — unselected days in the range will be treated as off.
5. Adjust time slots for each selected day.
6. To set the same hours across all selected days, leave the "Set different hours per day" toggle off and edit the single time slot that applies to all days.
#### Time off exception
1. Select a **date range**.
2. Optionally add a **label** (e.g. "Holiday", "PTO", "Conference") to identify the exception.
3. You will be off for the entire date range — no hours are bookable during this period.
Exceptions appear collapsed in the list. Click an exception card to expand and edit it. Click the **trash icon** on the card to delete an exception.
### Encounter Type Schedules
Encounter Type Schedules let you set dedicated availability windows per encounter type, so specific encounter types can be booked within defined hours alongside your default working hours.
1. Click **Add Availability Window** in the Encounter Type Schedules section.
2. A new schedule rule appears. Click **+** to add encounter types to the rule, or use the search to find templates.
3. Click **Select All** to assign all remaining encounter types to this rule.
4. Set the days and time slots for this rule, and optionally add exceptions.
5. Add additional rules for different encounter types by clicking **Add Schedule Rule**.
Each encounter type can only appear in one schedule rule at a time.
> **Warning indicator:** If a schedule rule has no encounter types assigned to it, a small warning dot appears next to the rule name. Hover over it to see the message *"Select at least one encounter template."* Add at least one encounter type to the rule before saving to clear the warning.
> **Note:** All encounter types added to a schedule rule must exist in the current published Designer configuration. If you reference an encounter type that has been removed or not yet published, the schedule cannot be saved. If you see an error saying "Availability encounters are not present in the current formation version", remove the unrecognized encounter type and try again — or publish the encounter type in Designer first.
***
## Sync with Calendar tab
The Sync with Calendar tab (visible when enabled) lets you connect your Welkin calendar with an external calendar provider — either **Google Calendar** or **Outlook (Microsoft)**.
* Click **Connect** on the provider you want to sync with.
* Once connected, the provider shows a **Connected** status with your email address.
* To disconnect, click the **⋯** menu on the connected provider and select **Remove**.
You can connect to one external provider at a time. Switching providers disconnects the current one.
***
## Saving changes
A **Save** button and a **Cancel** button appear at the bottom of the page whenever you have unsaved changes. Click **Save** to apply your changes, or **Cancel** to discard them.
***
## Important notes
* Working hours are required for the phone tree to operate correctly.
* Each individual must configure their own working hours — a manager cannot set them on someone else's behalf. Contact your CSM for API-based workarounds.
* Date exceptions cannot have a start date in the past (when creating a new exception).
* Exception date ranges cannot overlap each other within the same schedule.
* If sync with Acuity is enabled. When Encounter Type Schedules are configured, Acuity will use them instead of the default schedule.
## More Questions?
Contact or your Implementation/CSM directly.
# Patients
## Overview
The Patients section is the central hub for managing your patient population in Welkin. From here you can search for patients, view your panel, create new patient records, and take bulk actions.
## Accessing the Patients Section
Click **Patients** in the left navigation bar of the Care Portal. By default, you will see the **My Patients** view — the list of patients assigned to you or your care team.
## Patient List Views
* **My Patients** — patients currently assigned to you
* **All Patients** — your full patient population (access may be restricted by your role)
* **By Program** — filter patients enrolled in a specific care program
* **By Phase** — filter patients by their current phase within a program
## Searching for Patients
Use the search bar in the upper right of the patient list to find patients. You can also use the filter dropdowns at the top to narrow results by:
* Date of birth
* Program
* Phase
* Region
* Territory
* Timezone
* Care member
Note: the search bar will only return results within the currently applied filters.
## Creating a New Patient
To add a new patient record, see [My Patients: Create and Search](/care/patients/patient-creation-and-search).
## Bulk Actions
Select multiple patients using the checkboxes to perform bulk actions such as:
* Update timezone
* Add cadences
* Update service areas
* Assign or reassign care team members
For details on bulk operations, see [My Patients and Bulk Edits/Actions](/care/patients/care-my-patients-and-bulk-edits-actions).
# Patient Profile
## Overview
The Patient Profile is the core record for each patient in Welkin. It contains all clinical, demographic, and operational information about the patient in one place.
## Accessing a Patient Profile
1. Navigate to **Patients** in the left navigation
2. Search for or click on the patient's name to open their profile
## Patient Profile Sections
The patient profile is organized into tabs and panels depending on your organization's configuration:
### Overview / Summary
A summary view showing key patient details: name, contact information, assigned care team, current program and phase, and recent activity.
### Demographics
Full demographic information including date of birth, gender, address, emergency contacts, and any custom patient attributes configured by your organization.
### Encounters
A chronological list of all encounters (visits, calls, messages, assessments) for this patient. Click any encounter to view the details or complete outstanding work.
### Assessments / Forms
Completed and outstanding assessment forms for this patient. Forms are associated with programs and phases, and may be assigned automatically when a patient enters a new stage of care.
### Documents
Uploaded documents, signed consents, and generated PDFs attached to the patient record.
### Messages
The full communication history for this patient across all channels (email, SMS, chat, calls).
### Tasks
Active and completed tasks assigned to care team members for this patient.
### Programs & Phases
The patient's enrollment in care programs and their current phase in each program.
## Editing Patient Information
To update demographic or contact information, see [Editing Patient Information](/care/patients/editing-patient-information).
***
## Related Topics
* [Patients](/care/patients/patients) – managing your patient population
* [Patient Profile Overview](/care/patients/patient-profile-overview) – profile sections
* [Editing Patient Information](/care/patients/editing-patient-information) – updating patient data
* [Patient Care Teams](/care/patients/patient-care-teams) – assigning care team members
* [Patient Programs and Phases](/care/patients/care-programs-and-phases) – program enrollment
* [Encounters](/care/encounters/encounters) – patient interactions
* [Forms and Assessments](/care/forms-and-assessments/forms-and-assessments) – patient assessments
* [Data Views](/care/data-views/data-views) – structured patient data
* [Patient Data View](https://docs.welkinhealth.com/designer/programs-and-profiles/patient-data-view) – Designer configuration
{% embed url="" %}
{% embed url="" %}
# Patient Profile Overview
## Overview
The Patient Profile Overview panel provides a quick-reference summary of the most important information about a patient. It is designed for care team members who need to orient themselves quickly before an encounter or task.
## What the Overview Shows
The patient profile overview typically includes:
* **Patient name and photo** (if uploaded)
* **Date of birth and age**
* **Contact information** – primary phone and email
* **Care team** – the assigned care team members for this patient
* **Program enrollment** – current programs and phases
* **Upcoming encounters** – next scheduled visit or call
* **Outstanding tasks** – tasks assigned to the care team for this patient
* **Recent activity** – last communication, last completed assessment, or last encounter
## Customizing the Overview
The fields displayed in the patient overview are configured in Designer using custom profile templates. Your organization may show additional fields such as insurance information, referring provider, or custom patient attributes.
Contact your Welkin administrator or Designer user if you need additional fields added to the overview panel.
## Related Pages
* [Patient Profile](/care/patients/patient-profile) – full patient profile documentation
* [Editing Patient Information](/care/patients/editing-patient-information) – how to update patient data
* [Patient Programs and Phases](/care/patients/care-programs-and-phases) – managing program enrollment
{% embed url="" %}
{% embed url="" %}
{% embed url="" %}
{% embed url="" %}
{% embed url="" %}
# Editing Patient Information
## Overview
Care team members can edit patient demographic and contact information directly from the patient profile, subject to their role permissions.
## How to Edit Patient Information
1. Open the **Patient Profile** for the patient you want to update
2. Click the **Edit** button or pencil icon next to the field or section you want to change
3. Modify the information as needed
4. Click **Save** to apply the changes
## Editable Fields
Depending on your organization's configuration and your role permissions, you may be able to edit:
* **Contact information** – phone numbers, email address, mailing address
* **Demographics** – date of birth, gender, preferred language, pronouns
* **Emergency contacts** – name, relationship, phone number
* **Custom patient attributes** – organization-defined fields such as insurance ID, referring provider, or health plan
* **Photo** – upload or update the patient's profile photo
## Permissions
Not all users can edit all fields. Some fields may be:
* **View-only** for certain roles
* **Restricted** to administrators or designated data managers
* **Auto-populated** from intake forms or integrations and locked from manual editing
If you cannot edit a field, contact your administrator to check your role permissions.
## Audit Trail
All changes to patient information are logged in the data audit trail. Administrators can review who changed what and when via the Admin Portal.
{% embed url="" %}
# My Patients: Create and Search
## Overview
The My Patients view provides your personalized patient list and tools for finding and creating patient records in Welkin.
## Searching for Patients
### Quick Search
Use the search bar at the top of the Patients section to find patients by:
* First Name + Middle Name + Last Name
* Phone
* Secondary Phone
* Email
* Secondary Email
* MRN
* NRIC
* Access Code
Results appear as you type. Click a result to open the patient profile.
### Advanced Filters
Use the **Filter** panel to narrow your patient list by:
* DOB
* Program
* Phase
* Region
* Territory
* Timezone
* Care Member
The **Phase** filter becomes active after you select a **Program**.
## Creating a New Patient
1. Click the **Create** button
2. Fill in the required fields:
* **First Name** and **Last Name**
* Any other fields configured as required in Designer
3. Optionally add additional demographic information
4. Click **Create** to add the new patient
## My Patients vs. All Patients
* **My Patients** shows only patients directly assigned to you or your care team
* **All Patients** shows the full patient population (subject to role permissions)
To switch between these views, use the **Care Member** filter: with your user selected, you see **My Patients**; remove your user from the filter to see **All Patients**.
{% embed url="" %}
# My Patients and Bulk Edits/Actions
## Overview
The My Patients view in Welkin supports bulk selection and bulk edits, allowing care team members to efficiently update multiple patient records at once.
## Searching and Filtering
You can narrow the patient list using the filter dropdowns at the top of the screen: DOB, Programs, Phases, Region, Territory, Timezones, and Care Members. Use the search bar in the upper right to find specific patients within the current filter selection.
## Selecting Multiple Patients
There are two ways to select patients for bulk edits:
1. Click the **Check All** checkbox at the top of the list to select all patients on the current page
2. Manually select individual patients using the checkbox next to each row
Once patients are selected, an **Edit** button will appear in orange.
## Available Bulk Actions
Click **Edit** to open a side panel with the following update options:
* **Timezone** — update the timezone for all selected patients
* **Cadences** — add cadences to selected patients
* **Service Areas** — update service area assignments
* **Care Teams** — assign or reassign care team members
## Important Notes
* Bulk edits apply to all selected patients on the current page simultaneously
* Bulk edits will **overwrite** any previously entered information for the updated field
* Review your selection carefully before applying changes
# Patient Care Teams
## Overview
In Welkin, each patient can be assigned to one or more care team members. The care team is the group of users responsible for managing a patient's care, and it determines who has visibility into and access to the patient record.
## Viewing a Patient's Care Team
1. Open the patient profile
2. The assigned care team is listed in the **Patient Overview** panel and in the **Care Team** tab
Care team members are shown with their name, role, and contact information.
## Assigning Care Team Members
To add a care team member to a patient:
1. Open the patient profile
2. Navigate to the **Care Team** tab or section
3. Click **+ Add Care Team Member**
4. Search for and select the user to add
5. Select their **role on the care team** (e.g., Primary Care Manager, Prescriber, Care Coordinator)
6. Click **Save**
## Changing the Primary Care Team Member
To change who is the primary or lead care team member:
1. In the Care Team tab, find the current primary member
2. Click the **role dropdown** next to their name
3. Select **Remove as Primary** or reassign the primary role to another team member
## Bulk Care Team Assignment
To assign a care team member to multiple patients at once, use the [bulk edit feature](/care/patients/care-my-patients-and-bulk-edits-actions).
## How Care Team Affects Access
A user must be on a patient's care team (or have a role with organization-wide patient access) to view that patient's full record. Restricting patient access to care team members is a common security configuration.
# Patient Programs and Phases
## Overview
Programs and phases in Welkin represent the structured care pathway a patient follows. Programs define the overall care track (e.g., Behavioral Health, Diabetes Management), and phases represent the stages within that track (e.g., Intake, Active Care, Maintenance, Discharged).
## Viewing a Patient's Programs and Phases
1. Open the patient profile
2. Navigate to the **Programs** or **Programs & Phases** tab
3. You will see all programs the patient is currently enrolled in and their current phase within each program
## Enrolling a Patient in a Program
1. In the patient profile, go to the **Programs** tab
2. Click **+ Enroll in Program**
3. Select the program from the list
4. If the program has an initial phase, the patient will be placed in that phase automatically
5. Click **Confirm**
## Changing a Patient's Phase
Phases can be changed manually or automatically via automations.
**To change manually:**
1. In the patient's Programs tab, click the current phase
2. Select the new phase from the dropdown
3. Confirm the phase change
The change will be logged with a timestamp and the name of the care team member who made the change.
## Discharging / Unenrolling a Patient
To remove a patient from a program:
1. In the Programs tab, click the **three dots** (⋯) next to the program
2. Select **Unenroll** or **Discharge**
3. Confirm the action
## How Programs Drive Workflows
Automations, assessments, and notifications can be triggered by program and phase. When a patient enters a new phase, configured automations may fire – sending reminders, assigning tasks, or generating assessments automatically.
For Designer-side configuration, see [Programs and Phases (Designer)](https://docs.welkinhealth.com/designer/programs-and-profiles/programs-and-phases).
***
## Related Topics
* [Programs and Phases (Designer)](https://docs.welkinhealth.com/designer/programs-and-profiles/programs-and-phases) – configuring programs and phases
* [Patients](/care/patients/patients) – managing your patient population
* [Automations](https://docs.welkinhealth.com/designer/automations/designer-how-to-create-automations) – automations triggered by program phase changes
* [Create User Notifications](https://docs.welkinhealth.com/designer/notifications-and-communications/create-user-notifications) – notifications on phase changes
# Goals
## Overview
Goals in Welkin allow care teams to set and track measurable objectives for patients. Goals can be clinical (e.g., reduce A1C below 7%), behavioral (e.g., walk 30 minutes 3x per week), or operational (e.g., complete intake assessments by a certain date).
## Viewing Patient Goals
1. Open the patient profile
2. Navigate to the **Goals** tab
3. All active and completed goals are listed with their target, current status, and due date
## Creating a New Goal
1. In the Goals tab, click **+ Add Goal**
2. Fill in the goal details:
* **Goal Name / Description** – what the goal is
* **Goal Type** – clinical, behavioral, or custom category
* **Target Value** – the measurable outcome to achieve (e.g., "A1C < 7.0")
* **Target Date** – when the goal should be achieved by
* **Assigned To** – which care team member is responsible for tracking
3. Click **Save**
## Updating Goal Progress
1. Click on a goal to open it
2. Update the **Current Value** or status (e.g., On Track, Behind, Achieved)
3. Add a note about progress if needed
4. Save the update
## Completing or Closing a Goal
When a goal is achieved:
1. Open the goal
2. Change the status to **Achieved** or **Completed**
3. Add a completion note
4. Save
Goals that are no longer relevant can be marked **Closed** with a reason.
## Linking Goals to Assessments
Goals can be linked to assessment scores so that progress is automatically tracked when assessments are completed. This is configured in Designer.
***
## Related Topics
* [Patient Profile](/care/patients/patient-profile) – goal tracking in patient records
* [Forms and Assessments](https://github.com/welkincloud-io/welkin-docs/blob/master/kb/care/forms-and-assessments.md) – assessment-driven tracking
* [Care Programs and Phases](/care/patients/care-programs-and-phases) – goals within programs
* [Patient Care Teams](/care/patients/patient-care-teams) – goal ownership
# Tasks
Tasks in Welkin are action items assigned to care team members, linked to a specific patient. They keep clinical workflows on track by capturing things that need to happen — follow-up calls, form completions, approvals, referrals, or any ad-hoc action that doesn't happen inside an encounter.
***
## Task structure
Each task includes:
* **Title / Description** — what needs to be done
* **Patient** — the patient the task is related to
* **Assigned to** — which care team member is responsible
* **Due date** — when the task should be completed
* **Priority** — urgency level (e.g., High, Normal, Low)
* **Status** — current state of the task
* **Created by** — the user or automation that created it
* **Notes** — optional additional context
***
## Task statuses
| Status | Description |
| --------------- | ----------------------------- |
| **To Do** | Task created, not yet started |
| **In Progress** | Task is being worked on |
| **Completed** | Task is done |
| **Cancelled** | Task is no longer needed |
***
## Creating a task
### From a patient record
1. Open the patient record
2. Navigate to the **Tasks** tab
3. Click **+ Add Task**
4. Fill in the title, assignee, due date, and priority
5. Click **Save**
The task is now visible both on the patient record and in the assignee's task list.
### From the global Tasks view
1. In the left sidebar, navigate to **Tasks**
2. Click **+ New Task**
3. Search for and select the **patient** to link the task to
4. Fill in the remaining fields and click **Save**
### Via automation
Tasks can be created automatically by Welkin's automation engine when specific conditions are met — for example, when a patient completes an assessment, enters a new program phase, or misses a scheduled encounter. Automation-created tasks follow the same structure and appear in the same views. For configuration details, see [Automation](https://docs.welkinhealth.com/designer/automations/designer-how-to-create-automations).
***
## Viewing and managing tasks
### Patient-level task list
All tasks for a specific patient are visible in the **Tasks** tab of their patient profile. You can filter by status, assignee, or due date.
### My Tasks / All Tasks view
The global **Tasks** view (accessible from the left sidebar) provides a list of:
* **My Tasks** — tasks assigned to the currently logged-in user
* **All Tasks** — all tasks across the organization (for roles with access)
Both views support filtering by patient, assignee, due date range, priority, and status.
***
## Completing a task
1. Open the task (from the patient record or the task list)
2. Update the status to **Completed**
3. Add a completion note if needed
4. Save
Completed tasks remain visible in the patient's task history for audit purposes.
***
## Reassigning a task
1. Open the task
2. Change the **Assigned to** field to a different care team member
3. Save — the new assignee will receive a notification
***
## Task reminders
When a task is approaching its due date or becomes overdue, Welkin sends a notification to the assignee. Notification settings can be adjusted in [User Profile](/care/getting-started/user-profile) and configured system-wide by administrators in Designer.
***
## Related articles
* [Care Portal Overview](/care)
* [Notifications & Alerts](/care/getting-started/notifications-and-alerts)
* [Patient Profile Overview](/care/patients/patient-profile-overview)
* [Automation](https://docs.welkinhealth.com/designer/automations/designer-how-to-create-automations)
# Forms and Assessments
Forms and Assessments are devices for structured data entry in Welkin. They allow care team members to collect clinical information, intake data, and patient-reported outcomes within a patient's record.
## Accessing Assessments
1. Click into a **patient profile** in the Care portal
2. Click **Assessments** in the patient navigation
3. You will see a list of in-progress and completed assessments
4. The list can be searched by name or sorted by clicking any column header
## Starting a New Assessment
1. Click the orange **Start Assessment** button in the top right corner
2. You will see a list of assessment templates available for this patient at their current stage
3. Select an assessment template to begin
4. Fill in the assessment answers
5. Click **Finalize** once complete
If you are not ready to finalize, you can save the assessment as a draft and return to it later.
## Filters
Care team members can search for specific forms using the **Filters** at the top of the Assessments page, making it easier to find assessments by type, status, or date.
## Completed Assessments
Completed assessments are stored in the patient record and can be reviewed at any time. Scored assessments display the total score and any configured result messages.
## Creating Assessment Templates
Assessment templates are configured in Designer. For instructions on building and configuring assessment templates, see [Creating Forms and Assessments](/care/forms-and-assessments/creating-forms-and-assessments).
# Creating Forms and Assessments
## Overview
Forms and assessment templates are created and configured in the Welkin Designer. Once published, they are available in the Care Portal for care team members to complete with patients.
## Steps to Create an Assessment Template
1. Log in to the **Welkin Designer**
2. Navigate to **Assessments** in the left sidebar
3. Click **+ New Assessment**
4. Enter the assessment **Name** (e.g., "PHQ-9", "Intake Form")
5. Choose the **Type** (e.g., Clinical, Patient-Reported, Scored)
## Adding Fields to the Assessment
1. Inside the assessment editor, click **+ Add Field**
2. Choose the field type:
* **Single-line text** – free text response
* **Multi-line text** – paragraph response
* **Number** – numeric input
* **Date** – date picker
* **Dropdown / Select** – predefined options
* **Multi-select** – multiple selections from a list
* **Yes/No / Boolean** – binary choice
* **Scale / Rating** – numbered scale (e.g., 0–10)
3. Set the field **label**, **placeholder text**, and whether it is **required**
4. Add conditional logic to show/hide fields based on other responses
## Configuring Scoring (for Scored Assessments)
1. For each response option, assign a **point value**
2. Configure the **total score calculation** (sum of all field scores)
3. Set **score thresholds** that display different result messages or trigger automations (e.g., score ≥ 15 triggers a high-risk alert)
## Associating Assessments with Programs
To associate an assessment with a program so it appears automatically when patients enter a specific phase:
1. In Designer, go to **Programs** → select the program and phase
2. Under **Assessments**, link the assessment to the phase
3. Publish the changes
For care team instructions on completing assessments, see [Forms and Assessments](https://github.com/welkincloud-io/welkin-docs/blob/master/kb/care/forms-and-assessments.md).
{% embed url="" %}
# Charts and Graphs
## Overview
Charts and graphs in Welkin provide visual representations of patient data over time. They are commonly used to track clinical metrics such as weight, blood pressure, assessment scores, or custom CDT (custom data type) values.
## Viewing Charts for a Patient
1. Open the patient profile
2. Navigate to the **Charts** or **Graphs** tab (the tab name may vary based on your configuration)
3. Select the data series or metric you want to view from the dropdown
The chart displays historical data points plotted over time, with the x-axis representing dates and the y-axis representing the metric value.
## Chart Controls
* **Date Range** – filter the chart to show data for a specific time period (last 30 days, last 90 days, custom range)
* **Data Point Selection** – if multiple metrics are available, toggle which ones to display
* **Zoom** – click and drag on the chart to zoom into a specific date range
## Data Sources for Charts
Charts pull data from:
* **Assessment responses** – scores from completed forms (e.g., PHQ-9 scores over time)
* **Custom Data Types (CDTs)** – structured data fields such as vitals, lab values, or biometric measurements
* **Encounter outcomes** – summary data captured during encounters
## Configuring Charts in Designer
Charts are configured in the Welkin Designer. Administrators and Designer users can:
* Define which data fields to chart
* Set axis labels and display formatting
* Configure chart types (line, bar, scatter)
For configuration details, see [How to Configure Charts and Graphs (Designer)](https://docs.welkinhealth.com/designer/charts-and-graphs/charts-graphs-how-to-configure).
{% embed url="" %}
# Document Management
## Overview
Document management in Welkin allows care teams to upload, organize, view, and share documents attached to patient records. Common document types include consent forms, referral letters, lab results, insurance cards, and signed agreements.
## Accessing Patient Documents
1. Open the patient profile
2. Navigate to the **Documents** tab
3. All documents attached to this patient are listed with their name, type, upload date, and uploader
## Viewing a Document
Click on any document in the list to open a preview or download it to your device.
## Document Categories
Documents are organized by **category** (document type). Categories are configured by your organization in Designer. Common categories include:
* Signed Consents
* Lab Results
* Insurance Documents
* Clinical Notes / Referrals
* Identity Documents
## Uploading Documents
To upload a new document to a patient record, see [Upload Documents](/care/documents/upload-documents).
## Document Expiration
Documents can be configured with an **expiration date** (e.g., for consent forms that must be renewed annually). Expired documents are flagged in the document list and may trigger automated renewal reminders.
## DocuSign Integration
If your organization uses DocuSign for electronic signatures, signed documents are automatically attached to the patient's record upon completion. See [DocuSign Overview (Care)](https://docs.welkinhealth.com/integrations/docusign/docusign-overview-care).
## Permissions
Access to documents is controlled by role. Care team members may be restricted to viewing only documents in certain categories. Contact your administrator if you need access to a document type you cannot see.
***
## Related Topics
* [Upload Documents](/care/documents/upload-documents) – uploading documents to patient records
* [DocuSign Overview (Care)](https://docs.welkinhealth.com/integrations/docusign/docusign-overview-care) – electronic signature integration
* [Configure Document Types](https://docs.welkinhealth.com/designer/documents-and-assessments/document-types-how-to-configure) – configuring document types in Designer
* [Patient Profile](/care/patients/patient-profile) – patient records overview
* [Roles](/care/getting-started/roles) – document access control
{% embed url="" %}
# Upload Documents
## Overview
You can upload documents directly to a patient's record in the Welkin Care Portal. Uploaded documents are attached to the patient's profile and accessible to care team members with the appropriate permissions.
## How to Upload a Document
1. Open the patient profile
2. Navigate to the **Documents** tab
3. Click **+ Upload Document** or **+ Add Document**
4. In the upload dialog:
* **Select file** – click to browse your device and select the file
* **Document type / category** – select the appropriate category (e.g., Lab Results, Signed Consent)
* **Document name** – edit the display name if needed (defaults to the file name)
* **Expiration date** – optionally set an expiration date for documents that need renewal
5. Click **Upload** to attach the document to the patient record
## Supported File Types
Welkin supports uploading the following file types:
* **Images**: JPG, JPEG, PNG
* **Documents**: PDF, DOC, DOCX
* **Spreadsheets**: XLS, XLSX, CSV
* **Video**: MP4
Maximum file size varies by organization configuration; contact your administrator if you receive a file size error.
## Viewing and Managing Uploaded Documents
After upload, the document appears in the patient's Documents tab. From there you can:
* **Preview** – view the document inline
* **Download** – save a copy to your device
* **Delete** – remove the document (subject to role permissions and retention policies)
## Automated Document Attachment
If your organization uses DocuSign, completed signed documents are attached automatically without manual upload. See [DocuSign Overview (Care)](https://docs.welkinhealth.com/integrations/docusign/docusign-overview-care).
{% embed url="" %}
## See Also
* [Document Management](/care/documents/documentmanagement) – viewing, organizing, and managing all patient documents
# Data Views
## Overview
Data Views in Welkin provide structured, tabular displays of patient data from Custom Data Types (CDTs). They allow care team members to review and input structured data – such as vitals, lab values, medications, or custom clinical data – in a spreadsheet-style interface.
## Accessing Data Views
1. Open the patient profile
2. Navigate to the **Data Views** or **CDT** section (the name depends on your organization's configuration)
3. Select the data type you want to view from the available list
## What Data Views Show
A data view displays rows of recorded data entries for a specific custom data type. Each row represents a single entry (e.g., a recorded blood pressure reading) and each column represents a field within that CDT (e.g., systolic, diastolic, date, notes).
## Adding a New Entry
1. In the data view, click **+ Add Entry** or **+ New Row**
2. Fill in the fields for the new entry
3. Click **Save**
## Editing an Existing Entry
1. Click on the row you want to edit
2. Modify the fields
3. Save the changes
Note: Editing may be restricted for finalized or locked entries depending on your organization's configuration.
## Exporting Data
From a data view, you may be able to export the data as a CSV file. Click the **Export** button if available.
## Configuration
Data Views are configured in the Designer using Custom Data Types. For configuration details, see [Custom Data Types (CDT Designer)](https://docs.welkinhealth.com/designer/custom-data-types/custom-data-types-cdt-designer).
***
## Related Topics
* [Custom Data Types](https://docs.welkinhealth.com/designer/custom-data-types/custom-data-types) – CDT fundamentals
* [Patient Data View](https://docs.welkinhealth.com/designer/programs-and-profiles/patient-data-view) – configuring data views in Designer
* [CDT Designer](https://docs.welkinhealth.com/designer/custom-data-types/custom-data-types-cdt-designer) – creating and managing CDTs
* [Patient Profile](/care/patients/patient-profile) – accessing data views from the patient view
* [AI Data View](/care/data-views/ai-widget) – AI-generated summaries in the patient profile
# AI Data View
## Overview
The AI Data View displays AI-generated content based on a patient’s record directly within the Care Portal. The content is generated according to the prompt configured for the data view in Designer, using the AI provider selected for your environment in Admin.
The AI Data View appears in the patient profile when an administrator adds it to a Dashboard.
***
## Reading the Summary
The widget card shows:
* **AI badge** — an "AI" label with a star icon identifies the widget as AI-generated content.
* **Title** — the name configured for this widget.
* **Generated on** — the date the current summary was produced.
* **Summary text** — the narrative summary of the patient's data.
***
## Summary States
| State | What you see |
| -------------- | -------------------------------------------------------------------------------------------------- |
| **Generating** | A loading skeleton or a spinner with "Thinking…" followed by partial text as the summary is built. |
| **Ready** | The full summary text is displayed with a "Generated on" date. |
| **Failed** | An error card reading "Unable to Generate Summary" with a **Refresh** button. |
| **No summary** | "No summary available." is shown if no data exists yet. |
***
## Refreshing the Summary
When the summary can be regenerated, a **sync icon (↻)** appears in the top-right corner of the widget header. Click it to request a new summary.
If the underlying patient data has changed since the last summary was generated, the widget may automatically trigger a new generation without any action required from you.
While a new summary is being generated the sync icon spins and the widget shows a "Thinking…" indicator. The previous summary text remains visible until the new one is ready.
***
## Failed Summaries
If generation fails, the widget displays:
* "Unable to Generate Summary"
* "We couldn't generate the summary at this time. Please try again."
* A **Refresh** button to retry immediately.
If the problem persists, contact your administrator to verify the AI Assistant configuration in Admin.
***
## Related Topics
* [Data Views](/care/data-views/data-views) — other structured data displays in the patient profile
* [New Homepage](/care/getting-started/new-homepage) — Dashboards and Widgets in the Care Portal
* [AI Assistant (Admin)](https://docs.welkinhealth.com/admin/apis-and-integrations/ai-assistant) — configuring the AI provider
* [AI Data View (Designer)](https://docs.welkinhealth.com/designer/ai-features/ai-data-view) — configuring the prompt and data references for this widget
# Encounters Overview
## Overview
Encounters in Welkin represent interactions between a care team member and a patient. An encounter can be a scheduled office visit, a telehealth call, a phone check-in, or any structured patient interaction that generates a clinical record.
## What an Encounter Includes
Each encounter contains:
* **Encounter type** – the category of visit (e.g., Initial Intake, Follow-up, Telehealth, Phone)
* **Date and time** – when the encounter occurred or is scheduled
* **Assigned clinician** – the care team member responsible for the encounter
* **Status** – Draft, Scheduled, In Progress, Completed, or Cancelled
* **Notes** – clinical documentation written during or after the encounter
* **Assessments** – forms or assessments completed as part of the encounter
* **Outcome / Disposition** – the result of the encounter and any follow-up actions
## Encounter Workflow
The typical encounter workflow in Welkin:
1. **Schedule** – an encounter is created and scheduled for a future date
2. **Prepare** – the care team member reviews the patient profile before the visit
3. **Conduct** – the encounter takes place; notes and assessments are completed in real time or shortly after
4. **Finalize** – the clinician reviews the draft, makes any final edits, and marks the encounter as Complete
5. **Follow-up** – tasks or automations triggered by encounter completion create next steps
## Encounter Types
Encounter types are configured in the Designer and determine which assessments, templates, and workflows apply. Common types include: Initial Consultation, Follow-up, Telehealth, Group Session, Phone Check-in.
For instructions on creating and managing encounters, see [Encounters](/care/encounters/encounters) and [Create, Modify, Complete Encounters](/care/encounters/encounters-create-modify-complete).
***
## Related Pages
* [Encounters (list view)](/care/encounters/encounters)
* [Create, Modify & Complete Encounters](/care/encounters/encounters-create-modify-complete)
* [Encounters in the Patient Profile](/care/encounters/encounters-in-the-patient-profile)
# Encounters
## Overview
Encounters are the core patient interaction records in Welkin. Every significant patient touchpoint – whether a scheduled appointment, a telehealth call, or a documented phone conversation – is recorded as an encounter.
## Viewing Encounters
Encounters can be viewed from:
* **Patient profile → Encounters tab** – all encounters for a specific patient
* **Calendar** – scheduled encounters shown as calendar events
* **My Work / Tasks** – encounters assigned to you that require action
## Encounter List
In the patient profile's Encounters tab, encounters are listed in reverse chronological order. Each row shows:
* Encounter type and date
* Assigned clinician
* Status (Scheduled, In Progress, Completed, Cancelled)
* A summary of the encounter or key data captured
Click an encounter to open the full record.
## Encounter Statuses
* **Scheduled** – the encounter is booked for a future date
* **In Progress** – the encounter has started; notes are being added
* **Draft** – documentation has been started but not finalized
* **Completed** – the encounter has been finalized
* **Cancelled** – the encounter was cancelled before it occurred
## Creating a New Encounter
See [Create, Modify, Complete Encounters](/care/encounters/encounters-create-modify-complete).
***
## Related Topics
* [Create, Modify, Complete Encounters](/care/encounters/encounters-create-modify-complete) – step-by-step guide to working with encounters
* [Forms and Assessments](/care/forms-and-assessments/forms-and-assessments) – assessments within encounters
* [Encounters and Dependencies](https://docs.welkinhealth.com/designer/notifications-and-communications/encounters-and-dependencies) – configuring encounters in Designer
* [Programs and Phases](/care/patients/care-programs-and-phases) – how programs trigger encounter workflows
{% embed url="" %}
## See Also
* [Encounters Overview](/care/encounters/feature-overview-encounters) – what encounters are and how they fit into workflows
* [Create, Modify & Complete Encounters](/care/encounters/encounters-create-modify-complete)
* [Encounters in the Patient Profile](/care/encounters/encounters-in-the-patient-profile)
# Create, Modify, Complete Encounters
## Overview
This guide walks through the full lifecycle of an encounter in the Care Portal – from creation to completion.
## Creating an Encounter
### From the Calendar
1. Navigate to **Calendar** and click a time slot or click **+ New Encounter**
2. Select the **Patient**
3. Select the **Encounter Type** (e.g., Initial Intake, Follow-up, Telehealth)
4. Set the **Date and Time** and **Duration**
5. Assign a **Care Team Member**
6. Click **Save**
### From the Patient Profile
1. Open the patient profile
2. Go to the **Encounters** tab
3. Click **+ New Encounter**
4. Complete the encounter details and save
## Conducting an Encounter
When the encounter time arrives:
1. Open the encounter from your calendar or the patient profile
2. Click **Start Encounter** to change the status to In Progress
3. Complete any **assessments or forms** embedded in the encounter template
4. Add clinical **notes** in the notes panel
5. Record any relevant data in associated CDTs
## Modifying an Encounter
To edit encounter details before completion:
1. Open the encounter
2. Click **Edit**
3. Modify the date, time, type, or assigned clinician as needed
4. Save changes
You can edit encounter notes at any time while the encounter is in Draft or In Progress status.
## Completing an Encounter
1. Review all notes, assessments, and data entered
2. Click **Complete Encounter** or **Finalize**
3. If draft mode is enabled, the encounter enters a draft state for final review before locking
4. Once finalized, the encounter is locked and cannot be edited without admin intervention
## Cancelling an Encounter
1. Open the encounter
2. Click **Cancel Encounter**
3. Select a cancellation reason (if configured)
4. The encounter status changes to Cancelled
# Encounters in the Patient Profile
## Overview
All encounters for a patient are accessible directly from the patient's profile. The Encounters tab provides a comprehensive history of every interaction – past, present, and scheduled – for that patient.
## Accessing Encounters from the Patient Profile
1. Open the patient profile
2. Click the **Encounters** tab
3. All encounters are listed in reverse chronological order
## Encounter List Display
Each encounter in the list shows:
* **Encounter type** (e.g., Initial Intake, Follow-up, Telehealth)
* **Date and time** – when the encounter occurred or is scheduled
* **Assigned care team member** – the clinician or coordinator who owns the encounter
* **Status** – Scheduled, In Progress, Draft, Completed, or Cancelled
* **Summary** – key notes or assessment highlights
Click any encounter to open the full detail view.
## Filtering and Sorting Encounters
Use the filter controls above the encounter list to:
* Filter by **status** (show only Completed, only Draft, etc.)
* Filter by **encounter type** (show only telehealth visits, for example)
* Filter by **date range** (show encounters from the last 30 days, last 6 months, etc.)
* **Sort** by date (newest or oldest first)
## Creating a New Encounter
To schedule a new encounter directly from the patient profile:
1. Click **+ New Encounter** in the Encounters tab
2. Complete the encounter details
3. Save or schedule the encounter
For full instructions on creating and completing encounters, see [Create, Modify, Complete Encounters](/care/encounters/encounters-create-modify-complete).
# Communication Center
## Overview
The Communication Center in Welkin is the hub for all patient and care team communications. It consolidates messages, calls, SMS, email, and chat into a single interface so care team members can manage all interactions without switching between applications.
## Accessing the Communication Center
Click **Messages** or **Communication** in the left navigation bar of the Care Portal.
## Communication Channels
The Communication Center supports multiple channels depending on your organization's configuration:
* **Email** – send and receive emails with patients
* **SMS** – two-way text messaging with patients via configured phone numbers
* **Secure Email** – HIPAA-compliant encrypted email (requires Paubox or similar)
* **Chat** – live chat with patients via the Welkin patient portal
* **Voice Calls** – inbound and outbound call routing
## Viewing Conversations
The Communication Center shows a list of all active and recent conversations. Each conversation is linked to a patient record. Click a conversation to view the full message thread.
## Sending a Message
1. From the Communication Center or from within a patient profile, click **+ New Message** or the channel icon
2. Select the patient (if not already in the context of a patient profile)
3. Choose the communication channel (Email, SMS, etc.)
4. Compose your message
5. Click **Send**
## Inbox
For enhanced inbox management features including filtering, assignment, and threaded messaging, see [Inbox](/care/communication/inbox).
## Managing Unrecognized Communication
For messages received from unknown numbers or addresses, see [Manage Unrecognized Communication](/care/communication/manage-unrecognized-communication).
***
## Related Topics
* [Inbox](/care/communication/inbox) – inbox management and filtering
* [Communication Templates](/care/communication/communication-templates) – message templates
* [Calls](/care/communication/communication-center-calls) – phone call management
* [Chat](/care/communication/chat) – live chat functionality
* [SMS](/care/communication/communication-center-sms) – text messaging
* [Email](/care/communication/email-functionality) – email functionality
* [Manage Unrecognized Communication](/care/communication/manage-unrecognized-communication) – handling unknown senders
* [Notifications and Alerts](/care/getting-started/notifications-and-alerts) – system notifications
* [Automations that Trigger Outbound Communications](https://docs.welkinhealth.com/designer/automations/automations-that-trigger-outbound-communications) – automated messages in Designer
# Inbox
## Overview
The Inbox is a centralized communication workspace in Welkin that brings all patient conversations into one place across Secure Email, Email, SMS, and Live Chat. Instead of managing messages one patient at a time or switching between pages and tools, care teams can view, triage, and respond to communications across multiple patients and channels from a single inbox.
Embedded directly into the Care Portal navigation, the Inbox supports both individual provider workflows and team-based collaboration. Messages can be assigned, tracked, and closed with clear ownership, ensuring that every patient inquiry is handled promptly and consistently. This structure helps prevent missed messages, duplicate replies, and breakdowns in handoffs between team members or shifts.
The Inbox is built on a real-time WebSocket architecture, so updates appear instantly as users interact with messages. Team members can see when others are viewing or typing in the same conversation, which enables smooth collaboration without page refreshes and reduces the risk of overlapping responses. At the same time, patient context such as demographics, care team information, and recent encounters remains available alongside each conversation, eliminating the need to navigate away to understand the full clinical picture.
Designed for healthcare operations at scale, the Welkin Inbox provides a secure, auditable record of all patient communications while remaining flexible enough to support different roles, permissions, and workflows. It turns patient messaging from a fragmented, reactive task into a coordinated, team-driven process that supports efficient care delivery and a consistent patient experience.
***
## The Designer Portal
### Enable Inbox
By default, the Inbox is not included in the Care Portal sidebar. To make it available, it must be explicitly added in the Designer for each role that requires access. This allows organizations to control which users can access the Inbox and which level of visibility they have.
To enable the Inbox, create a draft in the Designer and add the Inbox item to the menu configuration for the appropriate user role.
Once added, save the role configuration. If a user needs access beyond their personal inbox, additional permissions must be granted through Security Policies to allow access to shared or global inboxes.
After completing the configuration, publish the changes to make them available in the Care Portal.
### Permissions
When Inbox access is added to a role, **My Inbox** becomes available automatically. Access to shared inboxes is controlled through Security Policies.
* **Inbox Care Team** – allows users to access the Care Team Inbox.
* **Inbox Full Patient** – expands access to include both the Care Team Inbox and the All Patients Inbox, providing visibility across all patient communications within the permitted scope.
* **Inbox API** – allows API clients to access all inboxes programmatically.
***
## The Admin Portal
### Direction of Notifications for the Communication Center
In the Admin Portal, you can control where notification clicks direct users. Notifications can either open the new Inbox experience or continue routing users to the legacy patient communication center.
This setting is configured in **Admin Portal → Feature Settings → Environment → Inbox Notifications**.
When Inbox Notifications are enabled, clicking a notification opens the Inbox. When disabled, notifications continue to direct users to the patient-level communication center.
***
## The Care Portal
### Inboxes
Inbox availability depends on the permissions assigned to a user's role. Each inbox is designed to support a specific workflow and level of responsibility.
**My Inbox** is a personalized workspace where users manage communications related to their assigned patients. It includes:
* **Assigned to me** – communications assigned to the logged-in user
* **Primary Contact** – communications from patients where the user is set as primary contact
* **Unrecognized** – communications assigned to the user where no matching patient exists on their care team
* **Sent** – communications sent by the user
**Care Team Inbox** is a shared workspace for managing patient communications across a care team. It includes:
* **Directed** – communications from patients where the user is part of the care team
* **Unrecognized** – the email belongs to several patients, and the user is on the care team for some or all of them
**All Patients Inbox** provides a management-level view of all patient communications within the user's access scope. It includes:
* **Directed** – all incoming communications
* **Unrecognized** – all unrecognized communications
### Communication Status
Each communication has a status of **Open** or **Closed**. The goal is to respond in a timely manner and avoid leaving communications open unnecessarily.
Any incoming message automatically sets the communication status to Open, even if the conversation was previously closed. This indicates that staff action is required.
After a response is sent to the patient, the communication is automatically marked as Closed and appears in gray in the communications list, indicating that no further response is needed.
When sending a message, users can choose how the status is handled:
* **Send and keep Open** – sends the message without closing the communication, for cases where a follow-up is expected.
* **Send and Close** – sends the message and closes the communication. This is the default behavior when clicking Send.
The current communication status is shown next to the message input field and can be changed manually at any time.
### Message Sending Block
When you open a communication, you'll see a reply section below the conversation where you can type a message to the patient. This area shows who the conversation is associated with (a patient, a contact, or an unrecognized communication), the current communication status, and the Send button.
In the lower-left corner of the reply box, there are tools to help you compose your message:
* **Use a template** – Message templates can be created in the Designer. Clicking this icon opens a list of available templates. After selecting one, you can edit it as needed.
* **Text formatting** – Opens a small formatting toolbar for your message. Available for emails only.
* **Emoji** – Opens a panel with a selection of emojis you can add to your message.
* **Attach a file** – Opens the document picker, which includes all documents associated with the patient. You can also upload a file directly from your device.
* **Secure email** – Sends the message as a secure email. When selected, the Send button changes to "Send securely". Available for emails only.
### Patient Info
Each communication includes a patient information panel accessible from the patient icon on the right side of the conversation. This panel can be expanded or collapsed as needed.
The general information section displays the patient's name, age, and contact details. From this view, users can also open the patient profile to make edits if they have the appropriate permissions.
Additional profile information includes demographic details, preferred language, the patient's current local time, and contact methods. Phone numbers can be used to initiate calls when supported, and email addresses can be copied directly.
Care Team information shows the members involved in the patient's care, along with the designated primary contact.
The Recent Encounters section displays up to five encounters for the patient. The system first looks for upcoming encounters from the current date onward. If fewer than five future encounters are available, the most recent past encounters are added to reach a total of five. Selecting an encounter opens its detailed view.
### Search and Filters
The Inbox includes search and filtering tools to help users quickly locate communications. Messages can be searched by:
* Phone (to/from)
* Email (to/from)
* Patient/contact name
* Text content inside the communication
You can also use filters to find communications. By default, all filters are enabled, so all available communications are shown.
* **Status** – filter to view only Open or only Closed communications.
* **Channel** – filter by SMS, email, or chat.
Since the Care Team Inbox and the All Patients Inbox are used to manage shared patient communications, you can choose to view either all communications or only those that are not assigned to any user.
### Assigning Communication to a User
Incoming communications may be assigned automatically when the system can match the recipient address or number to a specific user. If a message is not assigned automatically, it can be assigned manually.
To assign a communication, users can select the **Assign** option in the communication header and choose from a list of available users. The list includes only users who have access to the related patient.
Once assigned, the communication appears in the selected user's inbox, and the assignment can be changed or removed if needed.
### Response to Unrecognized Email
Unrecognized communications must be linked to a patient before a response can be sent. To do this, users assign the communication to a patient using the **Link** option.
If multiple patients or contacts share the same email address or phone number, all matching records are shown for selection. If the correct patient is not listed, users can search for other records and complete the assignment manually. Once the communication is linked to a patient, it becomes eligible for response.
> **Note:** Currently, a communication must be assigned to a patient before a response can be sent. In a future update, staff will be able to respond to unrecognized messages directly.
### Threading in Communications
When an unrecognized email is first received, it must be assigned to a patient. After assignment, any replies received within the same email thread are automatically associated with that patient, eliminating the need for repeated manual assignment.
If the patient sends a new email outside the existing thread, it is treated as unrecognized and must be assigned again.
Threading is not supported for SMS messages, so each incoming SMS reply is treated as a separate unrecognized communication and must be assigned individually.
### SMS Sending Line
When sending an SMS, users can select the organizational phone number from which the message will be sent. If a label is configured for the number, it is displayed in the selection list; otherwise, the phone number itself is shown.
Each sending line creates a separate communication thread. If a patient exchanges messages across multiple lines, each line appears as a distinct communication in the Inbox. The selected sending line is displayed alongside the patient's name for clarity.
***
## Related Topics
* [Phone Channel](https://github.com/welkincloud-io/welkin-docs/blob/master/kb/care/inbox-phone-channel.md) – calls and voicemails in the Inbox
* [Internal Notes](https://github.com/welkincloud-io/welkin-docs/blob/master/kb/care/inbox-internal-notes.md) – private team notes within conversations
* [@Mentions](https://github.com/welkincloud-io/welkin-docs/blob/master/kb/care/inbox-mentions.md) – tagging colleagues in conversations
* [Deleting Records](https://github.com/welkincloud-io/welkin-docs/blob/master/kb/care/inbox-delete-records.md) – removing messages and communications
* [Communication Center](/care/communication/communication-center) – comprehensive messaging overview
* [Communication Templates](/care/communication/communication-templates) – message templates
* [Calls](/care/communication/communication-center-calls) – phone call management
* [Chat](/care/communication/chat) – live chat functionality
* [SMS](/care/communication/communication-center-sms) – text messaging
* [Email](/care/communication/email-functionality) – email functionality
* [Manage Unrecognized Communication](/care/communication/manage-unrecognized-communication) – unrecognized senders
# Phone Channel
The Phone channel in the Inbox consolidates all call-related communications — SMS messages, incoming calls, outgoing calls, and voicemails — into a single threaded view for each patient. This makes it easy for care teams to see the full communication history across messaging and calling without switching between different parts of the platform.
***
## Overview
The Phone channel was previously named the SMS channel. With the addition of call support, it has been renamed to reflect its expanded scope. All existing SMS communications remain in place; calls now appear within the same thread alongside messages.
***
## Call Records in the Phone Channel
When a call occurs — whether initiated by the care team or received from a patient — a call record is added to the Phone channel thread. Each record shows:
* **Call type** — incoming, outgoing, or missed
* **Duration** — the length of the connected call
* **Recording or voicemail** — if available, a playback control is displayed directly in the thread so users can listen without leaving the conversation
Call records appear in chronological order alongside any SMS messages in the same thread, giving a complete view of all interactions with that patient on the phone channel.
***
## Call Status and Communication State
Missed calls automatically set the communication status to **Open**, indicating that the patient attempted to reach the care team and a response is needed.
Completed incoming and outgoing calls do not change the communication status on their own. Status can still be managed manually or through the standard send-and-close workflow.
***
## Initiating a Call from the Inbox
Users can start a call to a patient directly from a Phone channel communication. Clicking the call option launches the existing Welkin call flow — the same experience used elsewhere in the platform. No changes have been made to how calls are conducted; the Inbox simply provides an additional entry point.
***
## Related Topics
* [Inbox](/care/communication/inbox) — Inbox overview and general usage
* [Calls](/care/communication/communication-center-calls) — call management in the Communication Center
* [SMS](/care/communication/communication-center-sms) — SMS messaging
# Internal Notes
Internal Notes allow care team members to leave private messages within a patient conversation in the Inbox. These notes are visible only to users with access to that communication — patients and external parties never see them.
Internal Notes are useful when team members need to share context, flag something for a colleague, or document an observation alongside a patient conversation without it appearing in the patient-facing message history.
***
## Adding an Internal Note
To add an Internal Note, open a conversation in the Inbox and switch the composer to **Add internal note** mode. Type your message and send it. The note is added to the conversation thread immediately.
Internal Notes are visually distinct from outbound messages — they are highlighted in **purple** and clearly labeled, making it easy to distinguish team notes from patient-facing communications at a glance.
***
## Visibility and Privacy
Internal Notes are only visible to users who have access to the communication. Patients, contacts, and any external parties cannot see Internal Notes — they are strictly internal to your care team.
All Internal Notes are saved as part of the conversation history and appear in chronological order alongside other messages in the thread.
***
## Using @Mentions in Internal Notes
Internal Notes support **@mentions**, allowing users to tag a specific colleague within a note. When a user is mentioned, they receive a notification and the conversation appears in their **Mentions** tab. See [Inbox: @Mentions](/care/communication/inbox/inbox-mentions) for full details.
***
## Related Topics
* [Inbox](/care/communication/inbox) — Inbox overview and general usage
* [Inbox: @Mentions](/care/communication/inbox/inbox-mentions) — tagging colleagues in Internal Notes
# @Mentions
@Mentions allow users to tag a specific colleague within an Inbox conversation, directing their attention to a message or thread. Mentions are currently available within [Internal Notes](/care/communication/inbox/inbox-internal-notes).
***
## Mentioning a Colleague
To mention a user, type **@** followed by their name in the Internal Note composer. An autocomplete list appears with matching users — select the person you want to tag and complete your message.
If the mentioned user does not have access to that conversation, a warning is shown before sending so you can decide how to proceed.
If the mentioned user's account has been deactivated, their name appears with a **\[Deactivated]** label wherever the mention is displayed. This applies both at the point of tagging and in the conversation history, ensuring mentions remain traceable even when team members leave.
***
## The Mentions Tab
A dedicated **Mentions** tab in the Inbox aggregates all conversations where you have been tagged. This gives you a single place to review and act on every mention directed at you, without having to search through individual conversations.
The tab shows a counter of **new mentions** — the number updates in real time as new mentions arrive or existing ones are marked as read.
***
## Mention Status
Each mention has a status of **New** or **Read**:
* **New** — the mention has not yet been viewed
* **Read** — the mention has been seen
Read mentions are visually distinct from new ones, making it easy to separate what still needs attention from what has already been seen.
***
## Notifications
Mention events can trigger automations in Designer, allowing you to send a notification to the mentioned user via the following action types:
* Notification
* Email User
* SMS User
* Task
* Webhook
For the Notification action type, the body field is not shown — the notification automatically includes the relevant portion of the message content.
To configure mention notifications, add a new automation using the **Mentions** event group in Designer.
***
## Related Topics
* [Inbox](/care/communication/inbox) — Inbox overview and general usage
* [Inbox: Internal Notes](/care/communication/inbox/inbox-internal-notes) — composing internal team messages
* [Automated Notifications](https://github.com/welkincloud-io/welkin-docs/blob/master/kb/designer/automated-notifications.md) — setting up automation-based notifications
# Deleting Records
Users can delete individual messages and entire communications from the Inbox.
***
## What Can Be Deleted
The following record types support deletion from the Inbox:
* SMS messages
* Email messages (inbound and outbound)
* Chat messages
* Call records
Both recognized communications (linked to a patient or contact) and unrecognized communications (not yet linked to any patient) can be deleted.
***
## How to Delete a Record
To delete a message or communication, hover over the item in the Inbox to reveal the action menu, then select **Delete**. The record is immediately removed from the view.
After clicking Delete, a short confirmation window appears — users have **15 seconds** to undo the deletion before it is finalized. Once the window closes, the record is replaced by a placeholder that shows the timestamp and the name of the user who performed the deletion.
The placeholder remains visible in the conversation thread so that the history of the communication is preserved for context, even though the content itself is no longer accessible.
***
## Audit Logging
All delete actions are recorded in the audit log, including the timestamp and the user who performed the deletion. This ensures a complete and auditable record of activity in the Inbox.
***
## Permissions
Deletion access is controlled through Security Policies in Designer. Users must have the appropriate permission to delete messages and communications.
***
## Related Topics
* [Inbox](/care/communication/inbox) — Inbox overview and general usage
* [Manage Unrecognized Communication](/care/communication/manage-unrecognized-communication) — handling unrecognized senders
# Fax
Welkin Health uses **Notifyre** as the fax vendor. Faxes are accessible from the Inbox in the Care Portal.
***
## Sending a Fax
The **Send Fax** button is available on both the Incoming and Sent Faxes tabs. Clicking it opens the fax sending form with the following fields:
* **Sender** — the fax number to send from. If multiple numbers have been configured, select the desired one from the drop-down list
* **Recipient** — the destination fax number
* **Subject** — the fax title
* **Related patient** — the patient the fax is associated with
* **Attachments** — files to include. Supported formats: JPG, PNG, PDF, DOC, XLS. Maximum 10 files with a combined size of up to 100 MB
By default, you can attach templates created in Designer or upload a file from your computer. If a patient is linked to the fax, you can also select files from that patient's Document Center.
You can preview each file before sending.
**Form actions:**
* **Save** — saves the fax as a draft, accessible in Fax Sent → Draft tab
* **Cancel** — discards the fax
* **Send Fax** — sends the fax immediately
***
## Search and Attachments
Faxes can be searched by:
* Phone number (`fromNumber` or `toNumber`)
* Subject
Attachments support the following file formats: `jpg`, `jpeg`, `png`, `pdf`, `docx`. Maximum 10 files with a total size of up to 100 MB.
# Manage Unrecognized Communication
## Overview
Unrecognized communications are inbound messages (SMS, email, or calls) received by your Welkin system from phone numbers or addresses that do not match any existing patient record. Welkin surfaces these in a dedicated queue so care teams can resolve them appropriately.
## Accessing Unrecognized Communications
1. Navigate to **Communication Center** (or **Messages**)
2. Look for the **Unrecognized** or **Unmatched** tab/section
3. All inbound messages without a matched patient record are listed here
> **Note:** The unrecognized voice calls queue includes all unrecognized calls, including any that were previously deleted or archived. This ensures no inbound contact attempt is permanently hidden from the queue.
## Resolving an Unrecognized Communication
For each unrecognized message, you have several options:
### Match to an Existing Patient
1. Click **Match to Patient**
2. Search for the patient by name, date of birth, or other identifiers
3. Confirm the match
4. The communication is linked to that patient's record and moved out of the unrecognized queue
### Create a New Patient Record
1. Click **Create New Patient**
2. Pre-fill the patient details using the information from the message
3. Complete the required fields and save
4. The communication is linked to the new patient record
### Archive / Ignore
If the message is spam or otherwise irrelevant:
1. Click **Archive** or **Dismiss**
2. The message is removed from the active queue and stored for audit purposes
## Preventing Unrecognized Communications
To reduce unrecognized messages:
* Ensure patients have current, verified phone numbers and email addresses in their records
* Configure duplicate detection settings in the Admin portal
* Remind patients to communicate from their registered contact information
# Communication Templates
## Overview
Communication templates in Welkin allow care teams to send consistent, pre-written messages to patients without composing each message from scratch. Templates support dynamic variables to personalize messages with patient-specific information.
## Accessing Templates
From the Communication Center, click the **Templates** icon when composing a message. You can also manage templates from the Care Portal settings or via Designer.
## Using a Template
1. Start composing a new message (email, SMS, or other channel)
2. Click the **Templates** or **Insert Template** button
3. Browse or search for the template you want
4. Click the template to insert it into your message
5. Review the populated message, modify if needed, and send
## Template Variables
Templates can include variables that are automatically replaced with patient-specific data, such as:
* `{{patient.first_name}}` – replaced with the patient's first name
* `{{patient.appointment_date}}` – replaced with their next scheduled appointment
* `{{care_team.name}}` – replaced with the sending clinician's name
Available variables depend on your organization's configuration.
## Creating Templates
Templates are created and managed in the Welkin Designer. To create a new template:
1. Log in to **Designer**
2. Navigate to **Communication Templates**
3. Click **+ New Template**
4. Select the channel (Email, SMS, etc.)
5. Write the template content using variables as needed
6. Save and publish the template
For Designer configuration, see the Designer documentation.
# Priority Cadence
## Overview
Priority Cadence is a patient-level communication scheduling feature in Welkin. It lets care teams define preferred delivery windows — by priority level — so that outbound notifications reach patients at the right time and frequency. When a notification is sent manually or triggered by an automation, selecting a priority causes the system to route delivery according to the cadence rules configured for that patient.
## Accessing Priority Cadence Settings
Priority Cadence is configured per patient from the **Communication Center** within the patient profile.
1. Open a patient record in the Care Portal
2. Navigate to **Comm Center**
3. Click **Communication Settings** (top-right corner of the Comm Center panel)
4. The **Priority Cadence** panel opens on the right side of the screen
## Priority Levels
There are three priority tiers, each with its own independent schedule:
| Priority | Typical use |
| ---------- | ---------------------------------------------------------------- |
| **Low** | Routine check-ins, informational messages, low-urgency reminders |
| **Medium** | Standard care follow-ups, appointment reminders |
| **High** | Urgent outreach, time-sensitive notifications |
Click the **Low**, **Medium**, or **High** tab to configure that tier.
## Configuring a Cadence Slot
Each priority tier supports multiple delivery slots. For each slot you can define:
* **Day of week** — select one or more days (SU, MO, TU, WE, TH, FR, SA) by clicking the day buttons
* **Time** — set the preferred delivery time (e.g., 8:00 AM)
* **Repeat every** — choose how often this slot recurs: every **1W**, **2W**, **3W**, **4W**, or **5W** (weeks). Multiple repeat intervals can be selected for the same slot.
Enable a slot by checking the checkbox on the left of the row. Disabled rows are ignored during delivery.
## How Priority Cadence Works with Notifications
When sending a notification — either manually from the Care Portal or via a Designer automation — you specify a **priority** (Low, Medium, or High). The system then schedules delivery according to the next available slot that matches the patient's cadence settings for that priority level.
For example, if a patient's Low cadence has a slot on Sundays at 8:00 AM repeating every 1W and 3W, a Low-priority notification will be queued for the next matching Sunday window.
## Notes
* Cadence settings are per patient and can be updated at any time from Communication Settings.
* If no cadence slot is configured for a selected priority, the notification may be delivered immediately or per the organization's default behavior.
* Priority Cadence applies to automated and manual outbound communications. It does not affect inbound messages.
***
## Related Topics
* [Communication Center](/care/communication/communication-center) — overview of the Comm Center
* [Communication Templates](/care/communication/communication-templates) — reusable message templates
* [Automations that Trigger Outbound Communications](https://github.com/welkincloud-io/welkin-docs/tree/master/kb/designer/automations-that-trigger-outbound-communications.md) — setting up automated notifications in Designer
* [Notifications and Alerts](/care/getting-started/notifications-and-alerts) — system notification settings
# Calls
## Overview
Welkin supports inbound and outbound voice calls directly within the Care Portal through integration with phone tree and VoIP providers. Calls are logged and linked to patient records for a complete communication history.
## Making an Outbound Call
1. Open the patient profile
2. Click the **phone icon** next to the patient's phone number, or navigate to **Communication Center** and click **+ New Call**
3. Select the patient's phone number to dial
4. The call is placed through your organization's configured phone system
If your organization uses a softphone integration, the call may initiate within the browser. If not, your desk phone or mobile device may ring to connect the call.
## Receiving Inbound Calls
Inbound calls are routed according to your organization's phone tree configuration. When a patient calls in:
* The system attempts to match the incoming number to a patient record
* If matched, the care team member receives a screen pop with the patient's information
* If unmatched, the call is presented as an unrecognized communication
## During a Call
While on a call, you can:
* Access the patient profile for reference
* Take notes that will be saved to the call log
* Complete a call disposition (e.g., Left Voicemail, Connected, No Answer)
## After a Call
All calls are logged in the patient's communication history with:
* Date and time
* Duration
* Direction (inbound/outbound)
* Disposition
* Notes entered during the call
## Call Recording
If call recording is enabled by your organization, recordings may be available in the call log. Access to recordings is controlled by role permissions.
For phone tree configuration, see [Phone Tree (Designer)](https://docs.welkinhealth.com/integrations/phone-and-sms/designer-phone-tree).
# Chat
## Overview
Welkin's Chat feature enables real-time text-based communication between care team members and patients through a secure, HIPAA-compliant messaging interface embedded in the Care Portal.
## Accessing Chat
Navigate to **Communication Center → Chat** in the Care Portal to view and respond to chat conversations.
## Starting a Chat
To initiate a chat with a patient:
1. Open the patient profile or go to the Communication Center
2. Click **+ New Chat** or the **Chat** icon
3. Select the patient
4. Type your message and press **Send**
The patient receives the chat message through their patient portal or a configured messaging channel.
## Chat Conversations
Each chat conversation is threaded by patient. All messages – sent and received – appear in chronological order within the conversation view. Unread messages are highlighted with a badge.
## Responding to Patient Chat
When a patient sends a chat message:
1. A notification appears in your Communication Center (and as a bell notification)
2. Click on the conversation to open it
3. Type your reply and send
## Chat Availability and Hours
If your organization has configured business hours for chat, messages received outside of those hours may receive an automated reply indicating when a care team member will respond.
## Chat Configuration
Chat requires configuration in both Designer and the Admin Portal:
* The chat webhook URL, API key, and secret must be entered in **Admin → Integrations → Communications**
* Chat must be activated in Admin for the channel to appear in the Care Portal
See [How to Turn On Communication Methods](https://docs.welkinhealth.com/admin/apis-and-integrations/communication-center-how-to-turn-on-your-communication-methods) for setup details.
# SMS
## Overview
Welkin supports two-way SMS (text message) communication between care teams and patients. SMS is managed through Twilio and configured by your administrator.
## Sending an SMS
1. Open the patient profile or go to the **Communication Center**
2. Click **+ New Message** and select **SMS**
3. Verify the patient's mobile number is listed (or select from available numbers)
4. Type your message (standard SMS character limit applies; long messages are sent as MMS)
5. Click **Send**
## Receiving SMS from Patients
When a patient replies via SMS:
* The message appears in the patient's communication thread in the Communication Center
* A notification badge appears on the bell icon and in the Inbox
* The SMS is logged in the patient's communication history
## SMS Templates
Use pre-written templates to send common messages quickly. Click the **Templates** icon when composing an SMS to browse available templates. See [Communication Templates](/care/communication/communication-templates).
## SMS Opt-Out
Patients can opt out of SMS communications by replying STOP to any message. Welkin automatically records the opt-out and prevents further SMS to that number until the patient opts back in (by replying START).
Opt-out status is visible in the patient profile. Care team members cannot send SMS to opted-out patients.
## Sending Line
Your organization may have multiple SMS sending lines (phone numbers). When sending, you may be able to select which line to send from, or the system may assign one automatically based on your configuration.
## Twilio A2P Requirements
SMS requires Twilio A2P (Application-to-Person) registration. See [Twilio A2P](https://docs.welkinhealth.com/integrations/phone-and-sms/twilio-a2p) for setup details.
# Email
## Overview
Welkin supports sending and receiving emails with patients directly from the Care Portal. Email is integrated into the Communication Center and patient profile, keeping all correspondence in one place.
## Sending an Email
1. Open the patient profile or go to the **Communication Center**
2. Click **+ New Message** and select **Email**
3. Confirm the patient's email address
4. Enter a **Subject** line
5. Compose the email body
6. Optionally attach files or use a template
7. Click **Send**
## Email Attachments
The following file types are supported as email attachments:
* **Images**: JPG, JPEG, PNG
* **Documents**: PDF, DOC, DOCX
* **Spreadsheets**: XLS, XLSX, CSV
## Receiving Patient Emails
When a patient replies to or initiates an email:
* The email appears in the Communication Center inbox
* The email is linked to the patient's record and stored in their communication history
* A notification is sent to the care team member assigned to the conversation
* Attachments in supported formats (images, documents, spreadsheets and HTML) are accepted and stored
## Email Templates
Use pre-written email templates to maintain consistent messaging. Click the **Templates** button when composing to select a template. See [Communication Templates](/care/communication/communication-templates).
## Secure / HIPAA-Compliant Email
For communications that contain protected health information (PHI), your organization may use **Secure Email** powered by Paubox. Secure emails are encrypted end-to-end. Recipients receive an email notification with a secure link to read the message.
To use Secure Email, select **Secure Email** as the channel when composing. See [Paubox Setup and Functionality](https://docs.welkinhealth.com/integrations/messaging/paubox-setup-and-functionality) for configuration details.
## Email History
All sent and received emails are stored in the patient's Communication tab. You can search the email history, filter by date, and view full email threads.
# Payments & Invoices
Welkin supports end-to-end patient billing through a built-in invoicing system backed by Stripe. Care teams and billing managers can create invoices from encounters or independently, collect payments via multiple methods, manage recurring subscriptions, and track patient balances — all without leaving Welkin.
> **Before you begin:** Stripe must be connected to your Welkin environment before invoices and payment collection can be used. See [Stripe Setup and Configuration](https://docs.welkinhealth.com/integrations/payments-stripe/stripe-setup-and-configuration).
***
## Invoice structure
An invoice is a financial document that creates a billing obligation for services or products rendered. Each invoice includes:
* **Client information** — patient name and responsible party details if different
* **Care member** — the provider associated with the services
* **Issue date** and optional **due date**
* **Date of service**
* **Line items** — service description, quantity, unit, and charges
* **Amount paid** and **balance owed**
* **Notes**
* **Created by** — either a system action or a user
***
## Invoice statuses
| Status | Description |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Draft** | Invoice created but not finalized. No payment method attached. Details can still be modified. |
| **Pending** | Invoice finalized with a payment method added. Awaiting payment. When a Stripe payment link is sent, the invoice stays Pending until the patient pays. |
| **Paid** | Payment successfully completed. |
| **Partially Paid** | A partial payment has been received. The invoice is not yet fully settled. |
| **Overdue** | The due date has passed without full payment. Status updates automatically. |
| **Deleted** | Soft-deleted invoice. No longer affects the patient balance, but the record is retained in the audit log. |
***
## Creating an invoice
### From an encounter
Invoices can be created directly within an encounter for any uninvoiced amount:
1. Open the patient's encounter in the Care portal
2. In the billing section, click **Create Invoice**
3. Services from the encounter are pre-populated — review and adjust as needed
4. Set the **due date** (optional) and add any **notes**
5. Click **Save** — the invoice is created in **Draft** status
Multiple invoices can be created for the same encounter to cover separate charges.
### Standalone invoice
Invoices can also be created independently of an encounter — for example, to charge a separate fee for paperwork or administrative services:
1. Navigate to the patient's **Billing** section or the organization-wide **Billing** tab
2. Click **Create Invoice**
3. Manually add line items with description, quantity, and amount
4. Set issue date, due date (optional), and notes
5. Click **Save** — invoice is created in **Draft** status
### Via automation
Invoices can be created automatically based on automation rules — for example, when a patient completes a payment through a Patient Facing Assessment (PFA), the system can generate the associated invoice automatically.
***
## Collecting payment
Once an invoice exists (in Draft or Pending status), you can collect payment using any of these three methods:
### 1. Charge card on file
If the patient has a saved payment method in Stripe:
1. Open the invoice
2. Select **Charge Card on File**
3. Confirm the charge amount
4. Click **Charge** — the card is billed immediately through Stripe
5. Invoice status updates to **Paid**
### 2. Send Stripe payment link
To let the patient pay on their own device:
1. Open the invoice
2. Select **Send Stripe Invoice Link**
3. Stripe sends a secure payment link to the patient's email on file
4. Invoice moves to **Pending** status
5. Once the patient pays via the link, invoice status automatically updates to **Paid**
### 3. Report a cash payment
For payments collected outside of Stripe (cash, check, wire transfer):
1. Open the invoice
2. Select **Report Cash Payment**
3. Enter the amount received
4. Confirm — the payment is logged and the invoice status updates accordingly
***
## Subscriptions
Welkin supports recurring billing through subscriptions, allowing healthcare providers to charge patients on a regular schedule — weekly, monthly, or yearly. Subscriptions are managed via Stripe and are visible in the **Subscriptions** tab of the Billing section.
### How subscriptions work
A subscription automatically generates an invoice on each billing cycle. When a charge is due:
* If the patient has a **card on file**, it is charged automatically
* If there is **no card on file**, the invoice is created in **Draft** status and must be collected manually
### Creating a subscription
A subscription can be created in two ways:
**From the patient record:**
1. Open the patient record and navigate to **Billing → Subscriptions**
2. Click **Create Subscription**
3. Fill in the subscription details:
* **Name** — a label for the subscription plan
* **Amount** — charge per cycle
* **Start date** — when billing begins
* **End date** — optional; leave blank to continue until cancelled
* **Recurrence** — Monthly, Weekly, or Yearly
* **Number of recurrences** — optional limit; leave blank to run indefinitely
4. Click **Save**
**From the organization Billing tab:**
1. Navigate to the **Billing** tab in the main menu
2. Click **Create Subscription** and select the patient
3. Fill in the same fields as above
Subscriptions can also be initiated programmatically via the Welkin API — for example, when a patient self-enrolls through a patient-facing form or landing page.
### Managing subscriptions
* **Edit** — subscription details can be updated before the next billing cycle processes
* **Cancel immediately** — stops the subscription at the current date; no further invoices are generated
* **Cancel on a future date** — sets an end date; the subscription continues until that date, then stops automatically
* **Multiple subscriptions** — a patient can have more than one active subscription (e.g., one for a membership plan and one for a recurring service fee)
### Failed payments
If a subscription payment fails (e.g., expired card), Stripe will retry according to your [Stripe retry settings](https://dashboard.stripe.com/settings/billing/automatic). Failed payment attempts are logged in the patient's billing history. You can resolve a failed payment by updating the patient's card on file and retrying the charge.
***
## Managing invoices
### Patient-level invoice list
All invoices for a patient are accessible from the **Billing → Invoices** section of their patient record. The list supports sorting and filtering by status, date, and amount.
### Organization-level billing tab
A general billing view across all patients is available for billing managers. It includes:
* **Invoices** — all patient invoices across the organization, filterable by status, date, and amount
* **Subscriptions** — all active and past subscriptions
* **Claims** — insurance claims (if Candid integration is enabled)
### Editing an invoice
* **Draft invoices** can be fully edited (add/remove line items, update amounts, change notes)
* **Once finalized** (Pending or later), the invoice cannot be modified — delete it and create a new one if changes are needed
* An invoice cannot be deleted until all associated payments have been refunded
***
## Patient balance
Welkin maintains a running **patient balance** that reflects the net of all invoices and payments:
* When an invoice is created, the patient's outstanding balance increases by the invoiced amount
* When a payment is applied, the balance decreases accordingly
* Draft and deleted invoices do not affect the patient balance
* The balance is visible in the patient record and updates in real time
***
## Issuing refunds
Refunds are processed through Stripe and are available for any paid or partially paid invoice:
1. In the patient's payment history, locate the charge to refund
2. Click **Refund**
3. Enter the refund amount (up to the original charge)
4. Confirm — Stripe processes the refund, which appears on the patient's statement within 5–10 business days
5. Invoice status updates to **Partially Paid** (partial refund) or back to **Pending** (full refund)
> **Note:** A full refund does not delete the invoice. The invoice remains in the audit history.
***
## Invoice PDF templates
Welkin supports custom invoice PDF templates that can be configured in Designer:
1. Go to **Designer → Invoice Templates**
2. Upload your organization's invoice template (supports Welkin template variables for patient name, service date, line items, totals, etc.)
3. Multiple templates can be configured for different use cases
Generated invoice PDFs are stored in the patient's Document Center and can be sent manually by attaching them to an outbound email or message.
***
## API access
Invoices and subscriptions can be created, updated, and managed programmatically via the Welkin API. Key capabilities include:
* Create a new invoice for a patient
* Update invoice status
* Retrieve invoice details and payment history
* Create and manage subscriptions
* Trigger invoice or subscription creation from automation rules
Refer to the [Welkin API Postman Collection](https://docs.welkinhealth.com/developer-and-integration-guide#postman-collection) for the full list of invoice and payment endpoints, including example requests and response schemas.
For API authentication setup, see [Provisioning API Client](https://docs.welkinhealth.com/admin/apis-and-integrations/provisioning-api-client).
***
## Related articles
* [Stripe Setup and Configuration](https://docs.welkinhealth.com/integrations/payments-stripe/stripe-setup-and-configuration)
* [Welkin API Postman Collection](https://docs.welkinhealth.com/developer-and-integration-guide#postman-collection)
* [Automation](https://docs.welkinhealth.com/designer/automations/designer-how-to-create-automations)
# Pre-Authorization
Payment pre-authorization temporarily holds funds on a patient's account prior to an encounter, ensuring sufficient coverage for expected costs. The pre-authorized amount is calculated based on the services added to the encounter before pre-authorization is triggered:
* **Billing Type: Insurance** — the Co-pay amount is used
* **Billing Type: Self-Pay** — the full service price is used
* **Billing Type: Unknown / No Billing Type** — treated as Self-Pay; full service price is used
Once a pre-authorization is scheduled or executed, manual invoice creation is disabled to prevent overcharging. Any further actions — such as applying a cancellation fee — must be handled through automations or manual updates by authorized users.
***
## Configuring Pre-Authorization Time
The timing for pre-authorization is a global environment setting configured in the **Admin Portal → Payments Settings**. Click **Edit Config** to enable or disable pre-authorization using the **Active** toggle and define how many hours before the encounter start time the pre-authorization should run.
***
## Managing Pre-Authorization in the Care Portal
When a pre-authorization is scheduled for an encounter, a notification appears when opening the encounter, showing the scheduled time and providing options to **Reschedule** or **Cancel** it.
**Reschedule** — specify a new number of hours before the encounter start time.
**Cancel** — cancels the pre-authorization for this encounter. It can be rescheduled later using the Reschedule button.
If the encounter start date changes, the pre-authorization automatically adjusts to the new time based on the environment's pre-authorization settings.
***
## Retry
If a pre-authorization fails, a notification is displayed. Once the cause is resolved (e.g., a patient card is added), a **Retry** button becomes available to re-attempt the pre-authorization.
***
## Pre-Authorization Automation
Automations can be configured to handle funds upon encounter completion or cancellation:
| Event | Action | Description |
| ------------------- | ------------------------- | -------------------------------------------------------------------------------- |
| Encounter Finalized | Charge Pre-authorization | Charges the pre-authorized funds plus any services added after pre-authorization |
| Encounter Cancelled | Charge Cancellation Fee | Charges the sum of cancellation fees for all services on the encounter |
| Encounter Cancelled | Release Pre-authorization | Releases the held funds without charging |
To configure separate behaviors for cancellation, link the automation to a specific field in the encounter disposition.
***
## Manual Charge and Release
When a pre-authorization is active, authorized users can manually act on the held funds from the encounter in the Care Portal:
**Charge** — captures the payment. An invoice is generated for the current encounter cost. If services were added after pre-authorization, a single invoice is created covering two payments: the pre-authorized amount and the additional balance. If the encounter cost decreased after pre-authorization, the system charges the updated amount and automatically refunds the difference.
**Release Hold** — cancels the pre-authorization and releases the reserved funds back to the patient's account. After release, users can manually create invoices or reschedule the pre-authorization.
***
More Questions? Contact or your Implementation/CSM directly.
# Designer Overview
Overview of Welkin Designer, the no-code configuration environment for programs, profiles, forms, automations, navigation, security, and other Care portal settings.
## Welkin Designer Overview
Welkin Designer is Welkin's no-code configuration environment for the Care platform. Administrators and implementation teams use it to configure care programs, patient profiles, forms and assessments, custom data types, automations, navigation layouts, security policies, webhooks, and homepage settings.
Everything care teams use in the Care portal is configured here. That includes patient data collection, care workflows, role-based layouts, outbound communications, notifications, and reporting inputs.
Welkin has three applications: **Care**, **Designer**, and **Admin**. Designer sits between them. It uses settings from Admin and publishes the configuration that care teams use in Care every day.
***
## Designer Version Control and Configuration
Every change made in the Designer is tracked. The **Change Summary** shows a full audit trail of modifications by date, user, and section. Configurations can also be exported as a snapshot for backup or migration to another environment.
→ [Change Summary and Version History](/designer/version-and-configuration/change-summary-and-version-history) · [Export Designer Configuration](/designer/version-and-configuration/export-designer-configuration)
***
## Care Programs, Phases, and Profiles
Programs are structured care pathways that patients follow. Each program contains one or more **phases** that represent where a patient is in their care journey. Programs drive patient workflows, assessment scheduling, automations, and reporting.
**Profiles** define the layout of what care team members see when they open a patient record — which tabs, data panels, and components are visible per role or encounter type.
→ [Programs and Phases](/designer/programs-and-profiles/programs-and-phases) · [Designer Profiles Overview](/designer/programs-and-profiles/designer-profiles-overview) · [Patient Data View](/designer/programs-and-profiles/patient-data-view) · [Enable Patient Delete](/designer/programs-and-profiles/designer-enable-patient-delete)
***
## Custom Data Types (CDTs)
Custom Data Types are structured data models that extend the patient record with your organization's specific fields. CDTs can hold any type of structured data — clinical measurements, intake information, insurance details, and more. Fields can be text, numbers, dates, dropdowns, or formulaic calculations derived from other fields.
→ [Custom Data Types](/designer/custom-data-types/custom-data-types) · [CDT Designer](/designer/custom-data-types/custom-data-types-cdt-designer) · [CDT Configuration](/designer/custom-data-types/cdt-configuration) · [Formulaic CDT Fields](/designer/custom-data-types/create-formulaic-custom-data-type-fields) · [Custom Field Types](/designer/custom-data-types/custom-field-types)
***
## Assessments, Forms, and Patient-Facing Forms
Assessments and forms are structured questionnaires completed by care teams or patients. They can be scored, include conditional logic (show/hide fields based on responses), and be associated with programs or encounter types. Assessment results can populate CDT fields, trigger automations, or generate PDF documents.
**Patient Facing Assessments (PFAs)** are forms sent directly to patients to complete on their own device.
→ [Create an Assessment or Form Template](/designer/documents-and-assessments/how-to-create-an-assessment-or-form-template) · [Add Conditionality to Assessments](/designer/documents-and-assessments/how-to-add-conditionality-to-assessments) · [Configure Scored Assessments](/designer/documents-and-assessments/designer-how-to-configure-scored-assessments) · [Forms Conditional Logic](/designer/documents-and-assessments/forms-conditional-logic) · [Create PDFs from Forms/Assessments](/designer/documents-and-assessments/create-pdfs-from-forms-assessments) · [Create PFA Folders](/designer/documents-and-assessments/create-pfa-folders) · [Associate Assessments with Programs](/designer/documents-and-assessments/how-to-associate-assessments-with-programs) · [Add Assessments to a Template](/designer/documents-and-assessments/how-to-add-assessments-to-a-template)
***
## Documents
Document types define what categories of files care teams can upload and store in patient records — lab results, signed forms, clinical notes, and more. Each document type can have metadata fields and access controls.
→ [Configure Document Types](/designer/documents-and-assessments/document-types-how-to-configure)
***
## Charts & Graphs
Charts and graphs surface visual summaries of patient data — trending clinical values, assessment scores over time, and other longitudinal views. They are configured against CDT fields and displayed in the patient profile.
→ [How to Configure Charts and Graphs](/designer/charts-and-graphs/charts-graphs-how-to-configure) · [Filter, Change Date, and Data Points](/designer/charts-and-graphs/charts-graphs-filter-change-date-and-by-data-point)
***
## Care Portal Navigation and Layout
Navigation layouts define what sections appear in the left sidebar of the Care portal per role. The action bar can also be customized to surface frequently used actions at the top of patient profiles.
→ [How to Create Navigation Layouts](/designer/navigation-and-layout/how-to-create-navigation-layouts) · [Customize Action Bar](/designer/navigation-and-layout/customize-action-bar)
***
## Workflow Automations
Automations are rule-based workflows that trigger actions when conditions are met — sending a message, creating a task, updating a CDT field, changing a program phase, or generating a notification. Conditions can be based on patient data changes, calendar events, assessment completions, program enrollments, and more.
Advanced automations support multi-step logic, time delays (postponed tasks), and branching conditions.
→ [How to Create Automations](/designer/automations/designer-how-to-create-automations) · [Create Advanced Automations](/designer/automations/create-advanced-automations) · [Automations that Trigger Outbound Communications](/designer/automations/automations-that-trigger-outbound-communications) · [Create Automated Appointment Reminders](/designer/automations/create-automated-appointment-reminders)
***
## Tasks
Task types and configurations are defined in the Designer — including which categories of tasks care teams can create, required fields, and automation rules that trigger task creation automatically.
→ [Task Management (Designer)](/designer/tasks/task-management-designer) · [Create Tasks](/designer/tasks/create-tasks)
***
## Notifications, Messages, and Communications
The Designer controls when and how care team members are notified — triggered by automations, communication events, or system activity. Communication methods (SMS, email, calls, chat) are configured and enabled here, and message templates can be built with dynamic variables.
→ [Automated Notifications](/designer/automations/automated-notifications) · [Create User Notifications](/designer/notifications-and-communications/create-user-notifications) · [Turning On Notifications for Communications](/designer/notifications-and-communications/turning-on-notifications-for-communications) · [Encounters and Dependencies](/designer/notifications-and-communications/encounters-and-dependencies) · [SMS Opt-Out](/designer/notifications-and-communications/sms-opt-out) · [Configure Phone Names](/designer/notifications-and-communications/configure-phone-names)
***
## Webhooks
Webhooks allow Welkin to push real-time event data to external systems when specific actions occur — a patient enrolls, an assessment is completed, a CDT field changes. Each webhook is configured with an endpoint URL, event type, and optional filtering.
→ [Webhooks](/designer/webhooks/webhooks) · [How to Create Webhooks](/designer/webhooks/how-to-create-webhooks)
***
## Security
Security policies define attribute-based access control (ABAC) rules — who can see and do what, based on user roles, patient attributes, regions, and territories. Policies are created in the Designer and assigned to users in Admin.
→ [Configuring Security Policies](/designer/security/configuring-security-policies) · [Setup Security Policies](/designer/security/setup-security-policies) · [Security Policy Detail](/designer/security/security-policy-detail) · [Defining Regions and Territories](/designer/security/defining-regions-and-territories)
***
## Care Homepage Configuration
The new homepage layout — which widgets, dashboards, and sections appear on a care team member's home screen — is configured in the Designer.
→ [New Homepage Configuration](/designer/homepage-configuration/new-homepage-designer)
***
## Terminology & Help
Welkin supports customizable terminology so organizations can use their own language — renaming "patients" to "members," "encounters" to "visits," and so on. The Help section in Care can also be configured to surface custom documentation links.
→ [Welkin Naming Conventions Dictionary](/designer/terminology-and-help/welkin-naming-conventions-dictionary) · [Brand Terminology Flexibility](/designer/terminology-and-help/brand-terminology-flexibility) · [Help Section](/designer/terminology-and-help/help-section) · [Configure Help Section](/designer/terminology-and-help/configure-help-section)
***
## Visual Components
Visual components are configurable UI elements — data tables, panels, and other display elements — that can be added to patient profiles. Dependencies between visual components define how changes in one component affect others.
→ [Visual Components](/designer/documents-and-assessments/visual-components) · [Visual Components Dependencies](/designer/documents-and-assessments/visual-components-dependencies)
# Change Summary and Version History
## Overview
The Change Summary is the first page you see when logging into Designer. It provides a comprehensive view of all modifications made to your Welkin configuration during your current work session and historical versions of your configuration. Understanding how to work with drafts and versions is essential for managing configuration changes safely and collaboratively.
## Key Concepts
* **Draft** – A working copy of your configuration that you can edit without affecting production
* **Version** – A published snapshot of your configuration that is live in production
* **Change Summary** – A log of all modifications made within the current draft
* **Version History** – Complete history of all published versions over time
* **Publish** – The action that converts a draft into a live version
## Working with Drafts
### Creating a Draft
Drafts allow you to work safely without impacting production:
#### Option 1: Create from Current Version (Recommended for Most Changes)
1. On the Designer homepage, click **Create Draft**
2. Select **Create from current version**
3. Click **Submit**
**When to use:**
* Making updates to existing configuration
* Adding new features to current setup
* Modifying existing components
* Makes changes on top of current live version
#### Option 2: Create from JSON File (For Importing Previous Configurations)
1. On the Designer homepage, click **Create Draft**
2. Select **Create from file**
3. Click **Choose File** and select a JSON configuration file from your computer
4. Click **Submit**
**When to use:**
* Importing a previously exported configuration
* Restoring an older version you have saved
* Loading a configuration template
* Testing a configuration before it's live
### Viewing the Change Summary
Once you have an active draft, the Change Summary displays:
1. **Draft Name** – Identifier for this draft work session
2. **Changes Made** – Chronological list of all modifications:
* What was added (e.g., "Created new custom data type: cdt-vitals")
* What was modified (e.g., "Updated field 'medication\_name' in cdt-medications")
* What was deleted (e.g., "Deleted form: Old Survey Form v1")
* When each change was made (timestamp)
* Who made the change (if multi-user environment)
3. **Status** – Indicates if draft is ready to publish or has issues
### Understanding Changes Displayed
#### Changes by Component Type
**Custom Data Types (CDTs)**
* New CDT created
* Fields added to existing CDT
* Field properties modified (type, required status, etc.)
* CDT deleted or archived
**Visual Components (Forms, Charts, PDFs)**
* New form/assessment created
* Form questions modified
* Conditional logic added/updated
* PDF templates added
* Form deleted
**Programs and Phases**
* New program created
* Phases added/modified
* Program associations updated
* Program deleted
**Automations**
* New automation rule created
* Trigger or condition modified
* Action added/changed
* Automation deleted
**Security Policies**
* New policy created
* Role permissions modified
* Field-level security updated
* Policy deleted
**Message Templates**
* New template created
* Template content modified
* Variables or filtering updated
* Template deleted
### Reviewing Changes Before Publishing
Best practice workflow:
1. **Work in Draft** – Make all your configuration changes
2. **Review Change Summary** – Read through all changes made
3. **Verify Each Change** – Confirm each change is as intended
4. **Look for Unintended Changes** – Check if you accidentally modified something
5. **Test in Draft** (if possible) – Verify configuration works as expected
6. **Publish** – When satisfied with all changes
## Publishing and Creating Versions
### Publishing Your Draft
When you're ready to make changes live in production:
1. In the Change Summary, review all changes one final time
2. Click **Publish** button
3. System may ask for confirmation:
* "Are you sure you want to publish these changes?"
* Review the list of changes once more
4. Click **Confirm Publish** or **Yes**
5. Draft is now published as the new live version
6. All users in Care see the new configuration immediately
### What Happens When You Publish
* All changes in the draft become live
* Previous version is archived in version history
* A new version number is created
* Timestamp is recorded
* User/admin making change is logged
* All care team members see the new configuration
## Version History
### Accessing Version History
1. In Designer, look for **Version History** or **Versions** section (may be accessed from homepage or settings)
2. View complete list of all published versions:
* Version numbers (v1.0, v1.1, v2.0, etc.)
* Publication date/time
* Changes in each version
* User who published
### Reading Version Information
Each version shows:
* **Version Number** – Sequential identifier
* **Published Date** – When it went live
* **Published By** – User who published (if tracked)
* **Summary of Changes** – Key modifications in that version
* **Configuration Details** – Full configuration exported as JSON
### Comparing Versions
Some Designer interfaces allow version comparison:
1. Select two versions to compare
2. System shows differences between them:
* What was added
* What was removed
* What was modified
* Fields that changed values
### Reverting to a Previous Version (If Supported)
Some organizations can revert to a previous version:
1. In Version History, select the version you want to restore
2. Click **Revert** or **Restore** button
3. System creates a new draft based on that older version
4. Review changes and publish when ready
**Note:** Reverting creates a new version; it doesn't delete intervening versions. All history is preserved.
## Export and Backup Workflow
### Exporting Configuration
To create a backup of your current configuration:
1. In Designer, look for **Export** or **Download Configuration**
2. Click to export current live version as JSON file
3. Save the JSON file to your computer with a descriptive name:
* Example: `welkin-config-v2.0-2026-03-21.json`
* Include version number and date
### When to Export
* Before making major changes to configuration
* Before publishing significant updates
* Regular scheduled backups (weekly/monthly)
* Before switching configurations
### Using Exported Configurations
Exported configurations can be:
* **Backed up** – Stored safely for disaster recovery
* **Shared** – Sent to other team members for review
* **Imported** – Loaded into Draft via "Create from file" option
* **Documented** – Stored with version control alongside other company records
## Best Practices
1. **Frequent Drafts** – Create new drafts for distinct pieces of work rather than one massive draft
2. **Descriptive Naming** – If able to name drafts, use names indicating what you're working on
* "Add Depression Screening Assessment"
* "Update Security Policies for New Roles"
* "Fix Medication Automation Bug"
3. **Review Before Publishing** – Always review Change Summary before publishing
4. **Test First** – If possible, test changes in a staging environment
5. **Regular Backups** – Export and backup configuration regularly
6. **Change Log** – Keep external documentation of significant changes and why they were made
7. **Incremental Changes** – Publish smaller changes frequently rather than large batches infrequently
8. **Team Awareness** – Notify team before publishing changes that affect their workflows
9. **Version Documentation** – Document major version changes:
* What changed
* Why it changed
* Who requested the change
* When it was published
* Impact on care team
10. **Rollback Plan** – Know how to quickly revert if published changes cause problems
## Common Scenarios
### Scenario 1: Adding a New Assessment
1. Create Draft from current version
2. Create new Form/Assessment in Visual Components
3. Configure questions, fields, and conditional logic
4. Review Change Summary (should show 1 new form + multiple field additions)
5. Publish when ready
6. Assessment appears in Care app
### Scenario 2: Updating an Existing Field
1. Create Draft from current version
2. Navigate to the CDT and field that needs updating
3. Modify field properties (type, options, required status, etc.)
4. Review Change Summary (should show field update)
5. Publish
6. Field behavior changes in all assessments using it
### Scenario 3: Creating Multiple Interconnected Changes
1. Create Draft from current version
2. Create new CDTs and fields for a program
3. Create new assessments using those fields
4. Create automations that reference the assessments
5. Update security policies to control access
6. Review Change Summary (should show multiple additions across categories)
7. Publish as a coordinated release
### Scenario 4: Testing and Publishing Safely
1. Create Draft from current version
2. Make proposed changes
3. Review Change Summary and export as JSON
4. If possible, test with care team in staging environment
5. Collect feedback
6. Make adjustments if needed
7. Publish when team agrees
## Related Topics
* [Designer: Feature Overview](/designer) – Designer interface overview
* [Configuring Security Policies](/designer/security/configuring-security-policies) – Publishing security changes
* [Export Designer Configuration](/designer/version-and-configuration/export-designer-configuration) – Detailed export guide
* [Custom Data Types (CDT): Designer](/designer/custom-data-types/custom-data-types-cdt-designer) – Changes to CDT structure
* [How to Create an Assessment or Form Template](/designer/documents-and-assessments/how-to-create-an-assessment-or-form-template) – Creating new forms tracked in changes
# Multi-User Collaboration in Designer
## Overview
Designer supports multiple users working on the same environment's configuration. However, Designer does not sync draft state between users in real time: the draft you see in your browser reflects the state loaded when the page was opened. If a teammate makes changes in the same draft, your view may be out of date until you refresh the page. This page describes the recommended workflow to avoid version conflicts and lost work when several users collaborate in Designer.
## How Draft State Behaves with Multiple Users
* All users in the same environment work against the same draft on the server
* Each user's browser shows the draft state as of the moment the page was loaded
* Changes made by another user do **not** appear automatically — they appear after a page refresh
* A full logout/login is **not** required; a browser page refresh is enough to load the latest draft state
If users do not refresh, they may see different "versions" of the draft, and publishing from a stale view can result in incorrect version differences or loss of another user's recent changes.
## Recommended Workflow
### 1. Refresh the page before publishing
Always complete a full browser page refresh before publishing a draft. This loads any changes completed by other users, so the publish includes the actual latest state of the draft rather than a stale view. This is the single most important habit for avoiding lost work.
### 2. Coordinate before publishing
Confirm with other team members that no one is in the middle of edits before anyone publishes. Ideally, agree on who publishes and when — for example, designate one person as the publisher for a given working session.
### 3. Divide work by area
When possible, avoid having multiple people edit the same resources at the same time. Splitting work by configuration area (for example, one person works on CDTs while another works on Automations) reduces the chance of overlapping changes.
### 4. Review the Change Summary before publishing
After refreshing, review the Change Summary to verify the full set of changes about to be published — including changes made by teammates. If you see unexpected items, check with the team before proceeding.
## Quick Checklist Before Publishing
1. Refresh the browser page
2. Confirm no teammates are mid-edit
3. Review the Change Summary
4. Publish
## Related Pages
* [Change Summary and Version History](/designer/version-and-configuration/change-summary-and-version-history)
* [Export Designer Configuration](/designer/version-and-configuration/export-designer-configuration)
# Export Designer Configuration
## Overview
Welkin Designer allows you to export your current configuration as a file. This export is useful for backup purposes, auditing changes, or comparing configurations across environments.
## Exporting Your Configuration
1. Log in to the **Welkin Designer**
2. In the top navigation or settings menu, click **Export Configuration**
3. The configuration will be packaged and downloaded as a file (typically JSON or ZIP format)
4. Save the file to a secure location
The export captures your current published configuration including:
* CDT definitions
* Assessment templates
* Automation rules
* Program and phase structures
* Navigation layouts
* Security policies
* Communication templates
## Using the Export
The exported configuration can be used to:
* **Audit changes** – compare exports from different dates to understand what changed
* **Backup** – retain a snapshot of your configuration before making major changes
* **Documentation** – review the full configuration in a structured format
## Importing Configuration
Welkin does not currently support importing a configuration file directly through the Designer UI. Configuration changes must be made through the Designer interface. Contact Welkin support for guidance on environment migrations or configuration transfers.
## Version History
For tracking changes within Designer, see [Change Summary and Version History](/designer/version-and-configuration/change-summary-and-version-history).
{% embed url="" %}
# How to Create Automations
Automations enable you to instantly trigger another action based on predefined conditions.
To set up an automation, select "Automations" from the vertical menu bar in Designer.
Click on "+New" in the upper right corner
Enter a title for your automation.
Next, select a Trigger Type: Event, Scheduled, or Recurring
Note: When you select a general trigger category with multiple options below, that trigger will fire when any of the below actions occur. For example, selecting "Data Type" will trigger for all of "Data Type Created, Data Type Updated, and Data Type Deleted."
***
## Related Topics
* [Create Advanced Automations](/designer/automations/create-advanced-automations) – complex automation patterns
* [Create Automated Appointment Reminders](/designer/automations/create-automated-appointment-reminders) – common automation use case
* [Automations that Trigger Outbound Communications](/designer/automations/automations-that-trigger-outbound-communications) – SMS/email automations
* [Create User Notifications](/designer/notifications-and-communications/create-user-notifications) – user-facing notifications
* [Programs and Phases](/designer/programs-and-profiles/programs-and-phases) – automations triggered by program enrollment
# Create Advanced Automations
## Overview
Automations instantly trigger predefined actions based on specific conditions within Welkin. While many automations handle simple scenarios (such as sending a notification when an Assessment is completed), complex situations may require advanced automations with multiple triggers, conditions, and actions. This guide covers examples of advanced automation patterns and explains how to implement them effectively.
## Core Concepts
### Automation Components
Every automation requires three elements:
1. **Trigger Event** – The action that initiates the automation (e.g., Assessment completed, data field updated, date milestone reached)
2. **Conditions** – Logical rules that must be satisfied for the automation to execute
3. **Actions** – The response triggered when conditions are met (send notification, send message, create task, update data)
Advanced automations combine multiple conditions with AND/OR logic and may include time-based delays.
## Example: BMI Change Follow-up Automation
This automation monitors BMI changes and sends a follow-up message when no improvement is detected after three weeks.
### Trigger
* **Event Type:** "Data Type Updated"
* **Data Type Name:** "cdt-bmi" (system-calculated BMI field)
### Conditions
The automation includes the following conditions (all must be true for execution):
1. **Patient in Program/Phase:** Patient is enrolled in the "Physical Therapy-Education" program
2. **Initial Check:** On data update, record the BMI value and timestamp
3. **Delayed Check:** 3 weeks (21 days) after the original BMI update, check if:
* The patient is still in the Physical Therapy-Education program
* The BMI has **not improved** (current BMI ≥ original BMI from 3 weeks ago)
* The patient remains enrolled in the care program
### Actions
If all conditions are met:
* **Send Message** to the care team: "Patient's BMI has not improved after 3 weeks. Consider adjusting the care plan."
* **Create Task** for the assigned care team member to review the patient's exercise and nutrition plan
* **Send Notification** to supervisory role alerting them of the patient requiring intervention
### Implementation Steps
1. Log into Designer and create a new Automation
2. Set the trigger to "Data Type Updated" and select "cdt-bmi"
3. Add conditions using the condition builder:
* Add program/phase enrollment condition
* Set time-based condition for 21-day delay
* Add BMI comparison condition
4. Configure actions:
* Select "Send Message" and compose the follow-up notification
* Select "Create Task" and define the task details
* Add "Send Notification" and select recipient roles
5. Save and publish the automation
## Example: Conditional Assessment Escalation
This automation escalates patients to a higher level of care based on assessment scores.
### Trigger
* **Event Type:** "Assessment Completed"
* **Assessment Name:** "Depression Screening"
### Conditions
1. **Score Threshold:** Assessment score is ≥ 15 (indicating moderate-to-severe depression)
2. **Not Yet Escalated:** Patient is still in "Standard Care" program (not already escalated)
3. **Consent Status:** Patient has consented to behavioral health referrals
### Actions
* Move patient to "Intensive Behavioral Health" program automatically
* Send notification to behavioral health team that new patient was escalated
* Create task for care coordinator to schedule behavioral health appointment
* Send message to patient with behavioral health resources
## Example: Encounter-Based Follow-up Automation
This automation schedules a follow-up assessment after an encounter is completed.
### Trigger
* **Event Type:** "Encounter Completed"
* **Encounter Type:** "Initial Assessment"
### Conditions
1. Patient is enrolled in "Chronic Disease Management" program
2. Encounter was marked as "completed" (not cancelled)
3. 30 days have not already passed since encounter completion
### Actions
1. Schedule follow-up assessment to be sent 14 days post-encounter
2. Send message to patient asking them to complete the follow-up assessment
3. Create task for care team member to monitor completion
## Advanced Condition Patterns
### Time-Based Conditions
* **Absolute Dates:** "After January 1, 2026"
* **Relative Dates:** "30 days from today"
* **Field-Based Dates:** "21 days from when field X was last updated"
* **Periodic Checks:** "Check every Monday"
### Complex Logic
* **AND Conditions:** All must be true (e.g., "in program AND score > 10 AND not completed")
* **OR Conditions:** Any can be true (e.g., "high risk OR overdue assessment")
* **Nested Logic:** Combine AND/OR for sophisticated rules
### Field Comparisons
* **Field vs. Value:** "BMI > 30"
* **Field vs. Field:** "Current value > Previous value"
* **Field vs. Range:** "Score between 10 and 20"
## Best Practices for Advanced Automations
1. **Clear Naming** – Use descriptive names that indicate the trigger and purpose (e.g., "BMI-Monitor-21DayNoImprovement")
2. **Test Before Publishing** – Create test patients and verify automation behavior before enabling for production
3. **Avoid Recursive Triggers** – Ensure automations don't trigger themselves indefinitely
* Example: Don't set an automation that updates a field to trigger another automation that updates the same field
4. **Consider Performance** – Complex automations with many conditions may impact system performance
* Test with realistic data volumes
* Limit the number of daily-running automations
5. **Monitor Execution** – Regularly review automation logs to ensure they're working as intended
6. **Document Logic** – Maintain clear documentation of complex automations for team knowledge
7. **Use Drafts for Development** – Always work in Designer drafts before publishing to production
## Limitations
* Automations cannot reference fields from different CDTs in cross-type comparisons
* Circular trigger patterns (A triggers B, B triggers A) will be blocked
* Maximum execution time limits apply to prevent infinite loops
* Some real-time actions may have latency depending on system load
## Related Topics
* [Designer: How to Create Automations](/designer/automations/designer-how-to-create-automations) – Basic automation setup guide
* [Automated Notifications](/designer/automations/automated-notifications) – Sending notifications via automations
* [Automations that Trigger Outbound Communications](/designer/automations/automations-that-trigger-outbound-communications) – Message and SMS automations
* [Programs and Phases](/designer/programs-and-profiles/programs-and-phases) – Managing care pathways that automations reference
* [How to Add Conditionality to Assessments](/designer/documents-and-assessments/how-to-add-conditionality-to-assessments) – Assessment-based conditional logic
# Create Automated Appointment Reminders
Automating appointment reminders is a straightforward process, but requires two things before building:
* **Encounter type(s)** that will be associated with the reminders
* **Message template** to be sent as the reminder (including a reference to the Encounter date/time fields)
## Steps
Once you have the above ready, navigate to **Automations** from the vertical menu bar in Designer, and click **+New** in the upper right corner.
Enter or make the following selections:
* **Automation Title**
* **Automation Label** (optional)
* **Trigger Type:** Scheduled
* **Relative time** — set how far in advance the reminder should send (e.g., 1 hour before)
* **Encounter template** — choose a specific encounter type if the reminder applies to only one. If no encounter type is selected, the automation will trigger for all encounter types
In the **Conditions and Actions** area on the right:
* Add any conditional logic desired (optional)
* Select **SMS Patient**, **Chat Patient**, or **Email Patient** as the Action type, depending on the communication channel
* Choose the **Message Template** to send
Once configured, publish the automation.
***
More Questions? Contact or your Implementation/CSM directly.
# Automated Notifications
## Overview
Automations in Welkin can trigger in-app notifications to care team members, providing more sophisticated control over when and to whom notifications are sent compared to standard system notifications. Using automations to send notifications allows you to alert care team members to critical patient events, milestone completions, or conditions requiring intervention.
This guide explains how to create automations that deliver notifications with custom messaging to specific team members or roles.
## Differences: Automations vs. System Notifications
### System Notifications
System notifications are built-in Welkin alerts for standard events:
* Assessment completed
* Patient message received
* Appointment scheduled
* Patient enrolled in program
**Limitations:**
* Limited customization
* Can't add specific clinical context
* Apply to all users in a role
### Automated Notifications
Automations give you advanced control:
* **Custom triggers** – Fire on any event in your system
* **Detailed conditions** – Only alert when specific conditions are met
* **Personalized messages** – Include clinical data and context
* **Selective recipients** – Alert specific users or roles
* **Complex workflows** – Combine with other actions (send message, create task, update data)
## How to Create an Automated Notification
### Step 1: Create an Automation
1. Log into Designer
2. Click **Create Draft** to start a new configuration draft
3. Navigate to **Automations** in the left sidebar
4. Click **+ New** to create a new automation
For detailed automation creation steps, see [Designer: How to Create Automations](/designer/automations/designer-how-to-create-automations).
### Step 2: Define the Trigger Event
Choose what event initiates the notification:
**Common Trigger Types:**
1. **Assessment Completed** – When a patient finishes an assessment
* Example: "Send notification when Depression Screening is completed"
2. **Data Type Updated** – When a specific CDT field is updated
* Example: "Send notification when blood pressure is entered and it's > 140 systolic"
3. **Program Change** – When patient enrolled/dis-enrolled from program
* Example: "Send notification when patient enrolled in Intensive Intervention program"
4. **Date Milestone** – At a specific time interval
* Example: "Send notification 30 days after assessment was last completed"
5. **Encounter Completed** – When care team completes an encounter
* Example: "Send notification when Initial Assessment encounter is finished"
6. **Task-Related** – When task is created, completed, or overdue
* Example: "Send notification when task assigned to this user is overdue"
### Step 3: Add Conditions
Add conditions to ensure the notification only sends when truly needed:
**Condition Examples:**
* **Program/Phase Status** – "Patient is enrolled in Behavioral Health > Intake phase"
* **Field Value Thresholds** – "Blood pressure systolic > 140"
* **Assessment Score Range** – "Depression score > 15 (moderate-to-severe)"
* **Time-Based** – "30 days have passed since last assessment"
* **Field Comparison** – "Current value is higher than previous value by > 5%"
* **Multiple Conditions (AND)** – "Patient in program AND score > threshold AND not already notified in past 7 days"
Complex conditions prevent alert fatigue by only notifying when truly relevant.
### Step 4: Select "Notification" as the Action
1. In the automation editor, find the **Actions** section
2. Click **+ Add Action** or select from action dropdown
3. Choose **Notification** as the action type
4. You'll see three fields to configure:
## Configuring the Notification
### Field 1: Body
The message content displayed to the care team member:
**Good Notification Examples:**
```
Patient's blood pressure is elevated (SBP: 155 mmHg).
Follow-up call recommended.
```
```
Moderate-to-severe depression symptoms detected (PHQ-9: 18).
Patient may need psychiatric referral.
Consider scheduling urgent appointment.
```
```
Patient completed initial intake assessment.
Ready to enroll in treatment program.
Create care plan before next scheduled appointment.
```
**Tips for Effective Notification Text:**
1. **Be Specific** – Include relevant data values
* ✓ "BP 155/95" vs. ✗ "BP is high"
2. **Suggest Action** – Tell care team what to do
* ✓ "Consider psychiatry referral" vs. ✗ "Something might be needed"
3. **Include Context** – Why is this notification important?
* ✓ "Score indicates moderate depression requiring treatment escalation"
4. **Keep Concise** – Notification should be readable at a glance
* ✓ 1-2 sentences vs. ✗ Long paragraphs
5. **Use Variables** – Include patient/clinical data
* `{{patient_name}}` – Patient full name
* `{{patient_mrn}}` – Medical record number
* `{{field_value}}` – The triggering value
* `{{current_date}}` – Today's date
* `{{assessment_score}}` – Assessment result
**Example with Variables:**
```
Patient {{patient_name}} (MRN: {{patient_mrn}})
completed {{assessment_title}} with score {{assessment_score}}.
This indicates {{interpretation}}.
Review within 24 hours.
```
### Field 2: Care Team Member(s)
Specify who receives the notification:
#### Option A: Specific Care Team Members
1. Click the **Care Team Member** dropdown
2. Search for and select specific team members by name
3. Can select multiple members:
* Primary care provider
* Care coordinator
* Behavioral health specialist
4. All selected members receive the notification
**When to use:**
* Notifications requiring specific expertise
* Patient-specific follow-up assigned to certain provider
* Escalations to supervisor
#### Option B: By Role
1. Leave **Care Team Member** section empty
2. Go to **Role(s)** field
3. Select one or more roles:
* Care Manager
* Nurse
* Psychiatrist
* Supervisor
* Any custom roles configured in your system
4. All users with the selected role(s) receive the notification
**When to use:**
* Alert all members of a role to a condition
* When specific user assignment is unknown
* Shared responsibility situations
**Example Role Selections:**
* "Alert all Behavioral Health providers"
* "Alert supervisor and assigned care manager"
* "Alert all Nurses and Care Managers"
### Field 3: Role(s)
As noted above, select specific roles if not selecting individual users.
## Notification Behavior
### How Notifications Appear
Once published, when the automation triggers:
1. **In-App Notification** – Care team members see notification icon/badge in Care app
2. **Notification Center** – Notification appears in their notification list
3. **Timestamp** – Notification shows when it was triggered
4. **Actionable** – Often links to the patient or assessment triggering it
5. **Persistent** – Stays until user marks as read/resolved
### Notification Delivery Timing
* **Real-time** – Most notifications deliver within seconds
* **Delayed Notifications** – Some automations can delay (e.g., "Notify 2 hours after assessment is completed")
* **Batch Notifications** – System may batch multiple notifications in some cases
## Practical Examples
### Example 1: High Blood Pressure Alert
**Trigger:** Data Type Updated (blood pressure)
**Conditions:**
* Systolic pressure > 160 mmHg
* Patient in Hypertension program
**Action - Notification:**
```
Body: "Patient {{patient_name}} has elevated BP ({{systolic}}/{{diastolic}} mmHg).
Consider urgent follow-up or hospital referral."
Recipients: Role = "Nurse" OR Role = "Supervising Provider"
```
**Result:** Nurses and supervisors immediately notified of critical BP reading.
### Example 2: Depression Screening Follow-up
**Trigger:** Assessment Completed (PHQ-9)
**Conditions:**
* PHQ-9 score between 15-20 (moderate-to-severe)
* No notification sent in past 30 days
**Action - Notification:**
```
Body: "{{patient_name}} completed PHQ-9 screening (Score: {{score}}/27).
Moderate-to-severe symptoms detected.
Consider psychiatric referral or therapy intensification."
Recipients: Specific person = {{assigned_care_manager}}
```
**Result:** Patient's assigned care manager receives alert for personalized follow-up.
### Example 3: Treatment Non-Response
**Trigger:** Data Type Updated (assessment score)
**Conditions:**
* In program > 8 weeks
* Current score > baseline score (worsening)
* User has not been notified in 30 days
**Action - Notification:**
```
Body: "{{patient_name}} shows worsening symptoms.
Previous score: {{previous_score}}, Current: {{current_score}}.
Care plan adjustment may be needed.
Schedule review appointment."
Recipients: Role = "Care Manager"
```
**Result:** Care managers alerted to treatment non-response for prompt intervention.
### Example 4: Overdue Assessment
**Trigger:** Date Milestone (30+ days since last assessment)
**Conditions:**
* Patient is in active program
* Expected to complete quarterly assessment
**Action - Notification:**
```
Body: "{{patient_name}} is overdue for {{assessment_name}}.
Last completed {{days_ago}} days ago.
Consider sending reminder or scheduling completion."
Recipients: Role = "Care Manager"
```
**Result:** Care managers reminded to request assessment completion.
## Best Practices
1. **Be Selective** – Only trigger notifications for truly important events
* Too many notifications cause alert fatigue
* Care team may ignore or disable notifications
2. **Be Specific** – Include data that helps care team understand the alert
* Not: "Patient assessment completed"
* Yes: "PHQ-9 completed with score 22 (severe depression)"
3. **Suggest Action** – Tell recipients what to do next
* Makes it clear whether action is needed
* Reduces time to decision
4. **Include Timeline** – Indicate urgency
* "Review within 24 hours" vs. "Review when convenient"
5. **Target Appropriately** – Send to people who can act
* Don't alert entire team if only one person can help
* Use role-based alerts when ownership is shared
6. **Avoid Duplicates** – Don't create multiple automations for same event
* Consolidate similar triggers
* Can use multiple notification actions in one automation
7. **Test Notifications** – Before publishing
* Create test patient in automation conditions
* Verify notification appears correctly
* Verify it goes to right people
8. **Monitor** – Review notification effectiveness
* Do care team act on notifications?
* Are there too many/too few?
* Adjust conditions based on team feedback
9. **Document** – Keep notes on what each automation notification does
* Why was it created?
* What conditions trigger it?
* What action is expected?
10. **Regular Review** – Periodically audit automations
* Remove ones no longer needed
* Update for changing workflows
* Consolidate redundant alerts
## Combining Notifications with Other Actions
A single automation can perform multiple actions:
**Example Multi-Action Automation:**
```
Trigger: Assessment score indicates suicide risk
Conditions:
- Assessment = "Suicide Risk Screening"
- Score > 8 (elevated risk)
Actions:
1. Send Notification to: "Care Manager" + "Psychiatrist"
Message: "Elevated suicide risk detected. Immediate intervention needed."
2. Create Task for: "Care Manager"
Task: "Schedule urgent psychiatric evaluation for {{patient_name}}"
3. Send Message to: Patient
Message: "We're concerned about your safety. Please contact the crisis line: 1-800-XXX-XXXX"
4. Update Patient Field: "risk_flag" = "URGENT"
```
This creates a coordinated response: notification to clinical team, task assignment, patient contact, and data update.
## Related Topics
* [Designer: How to Create Automations](/designer/automations/designer-how-to-create-automations) – Basic automation creation
* [Create Advanced Automations](/designer/automations/create-advanced-automations) – Complex automation patterns
* [Automations that Trigger Outbound Communications](/designer/automations/automations-that-trigger-outbound-communications) – Message/SMS automations
* [Create User Notifications](/designer/notifications-and-communications/create-user-notifications) – Alternative notification method
* [Custom Data Types (CDT): Designer](/designer/custom-data-types/custom-data-types-cdt-designer) – Data triggering automations
# Automations that Trigger Outbound Communications
Automations can be used to send communications outside of Welkin to patients, users, and even patient Contacts.
There are additional inputs needed to prepare to trigger outbound communications, depending on the intended recipient and mode of communication:
**Patients (Email/SMS/Chat)**
* Message templates (Email/SMS/Chat) — see [How to Create an Assessment or Form Template](/designer/documents-and-assessments/how-to-create-an-assessment-or-form-template) for message template setup
* Phone name (SMS) — see [Configure Phone Names](/designer/notifications-and-communications/configure-phone-names)
**Users (Email, SMS)**
* Message templates (Optional)
* Phone Name (SMS)
**User Contacts (Email/SMS)**
* Message Templates (Email/SMS)
* Profile Type (Email/SMS) — see [Designer: Profiles Overview](/designer/programs-and-profiles/designer-profiles-overview)
* Phone Name (SMS)
***
## Creating the Automation
The process to create an automation to send an outbound communication is the same as any other automation. You will need a trigger event, any conditional logic, and then the Actions. See [How to Create Automations](/designer/automations/designer-how-to-create-automations) for more information.
Once you have chosen your trigger and conditions, select the type of outbound communication you want to send in the **Actions** area. In most cases you will be required to use one of the Message Templates you created previously. If you are only sending the message to a user on your team, you can craft the SMS or email content directly in the automation area after selecting one of the "user" type options.
## The "From" Field
In some scenarios, you will see a field marked **From**. This field selects the phone number that will be used in the outbound SMS. This allows you to align different message types to the appropriate phone number and its associated A2P campaign (such as marketing). Configuring this correctly is required to avoid phone carriers blocking your messages — see [Twilio A2P](https://docs.welkinhealth.com/integrations/messaging-communications/twilio-a2p) for more information.
## Sending to a Contact
When crafting a message to a Contact, you will see a **Profile** field. The Profile specifies the type of contact for a particular patient who you want to route the message to — for example: Physician, Significant Other, Power of Attorney. The options available depend on which Profile types you have already created in Designer.
***
More Questions? Contact or your Implementation/CSM for more information.
# Programs and Phases
## Overview
Programs are structured care pathways that patients follow in Welkin. Each program contains one or more **phases** – defined stages representing where a patient is in their care journey. Programs and phases are configured in the Designer and drive patient workflows, assessments, automations, and reporting.
***
## Programs
A program represents a care pathway (e.g., "Diabetes Management", "Behavioral Health Onboarding"). Patients can be enrolled in one or more programs simultaneously.
### Creating a Program
1. In the Designer, navigate to **Programs**.
2. Click **+ Add Program**.
3. Enter a **Name** (used in conditions, automations, and reporting – names are case-sensitive).
4. Optionally add a **Description**.
5. Save and publish when ready.
### Program Settings
* **Multiple enrollment** – by default, a patient can only be in a program once at a time. Re-enrollment behavior can be configured if your workflow requires it.
* **Auto-enrollment** – programs can be triggered automatically via Automations when a patient meets defined criteria.
***
## Phases
Phases are the stages within a program (e.g., "Intake", "Active Care", "Maintenance", "Discharged").
### Creating Phases
1. Open a program in the Designer.
2. Under **Phases**, click **+ Add Phase**.
3. Enter a **Name** for the phase (case-sensitive – must match exactly when used in conditions).
4. Set the phase **order** by arranging phases in the desired sequence.
### Phase Transitions
Phase transitions can happen:
* **Manually** – a care team member changes the phase in the patient's profile.
* **Automatically** – via an Automation that triggers a phase change when conditions are met.
***
## Using Programs in Automations and Widgets
Programs and phases are commonly used as conditions in:
* **Automations** – trigger actions on phase entry/exit
* **New Homepage Widgets** – filter patients by current phase or program (see [New Homepage Configuration](/designer/homepage-configuration/new-homepage-designer))
* **Assessments** – associate assessments with programs so they appear at the right stage
***
## Publishing
After configuring programs and phases, create a draft in the Designer and publish to make changes available in the Care Portal.
***
## Related Topics
* [Patient Programs and Phases](https://docs.welkinhealth.com/care/patients/care-programs-and-phases) – managing programs in Care
* [How to Create Automations](/designer/automations/designer-how-to-create-automations) – automations triggered by program enrollment
* [How to Associate Assessments with Programs](/designer/documents-and-assessments/how-to-associate-assessments-with-programs) – linking assessments to programs
* [New Homepage Configuration](/designer/homepage-configuration/new-homepage-designer) – program/phase widgets on homepage
# Designer Profiles Overview
## Overview
Profiles in the Designer define the structure of information displayed in the Care Portal for different entity types – primarily patients, but also for contacts and other record types. A profile consists of fields, sections, and layout configurations that determine what information care team members see and can edit.
***
## What Profiles Control
* **Which fields are displayed** – standard fields (name, DOB, contact info) and custom fields (CDTs)
* **Field order and grouping** – how fields are arranged into sections
* **Field editability** – which fields are read-only vs. editable
* **Conditional display** – fields that appear only when certain conditions are met
***
## Types of Profiles
* **Patient Profile** – the main record view for patients
* **Contact Profile** – the view for non-patient contacts linked to patients
* **Custom entity profiles** – if your organization uses custom entity types
***
## Configuring a Profile
1. In the Designer, navigate to **Profiles**.
2. Select the profile type you want to configure (e.g., Patient).
3. Click to open the profile editor.
4. Add, remove, or reorder **sections** and **fields**.
5. Configure field properties (label, editability, required status).
6. Create a draft and publish.
***
## Adding Custom Fields to a Profile
Custom fields from your Custom Data Types (CDTs) can be added to profiles. See [CDT Designer](/designer/custom-data-types/custom-data-types-cdt-designer) for how to create CDTs and their fields.
***
## Publishing
Profile changes must be published in the Designer before they appear in the Care Portal. Always test profile changes in a sandbox environment before publishing to production.
# Patient Data View
## Overview
The Patient Data View is a configurable table view within the patient profile that displays structured data from Custom Data Types (CDTs) in a grid format. It allows care team members to see a history of CDT records for a patient without opening each record individually – useful for tracking vitals, lab results, medications, or other recurring data points.
***
## What the Patient Data View Shows
The Data View displays:
* Rows of CDT records for the selected patient
* Configurable columns (each column maps to a CDT field)
* Sortable and filterable columns
* Date-stamped records showing when each entry was created
***
## Configuring a Patient Data View in the Designer
1. In the Designer, navigate to **Data Views** or **Patient Data View**.
2. Click **+ Add Data View**.
3. Select the **CDT** this view is based on.
4. Choose which **fields** to show as columns.
5. Set the **display name** for the view (shown as a tab in the Care Portal).
6. Configure column labels, order, and optional filtering.
7. Save and publish.
***
## Assigning Data Views to Roles
Data views can be role-restricted – only certain roles see specific data views in the patient profile. Configure this in the navigation or profile layout settings.
***
## Publishing
Create a draft and publish in the Designer to make the Data View available in the Care Portal.
For general data views in Care, see [Data Views](https://docs.welkinhealth.com/care/data-views/data-views).
***
## Related Topics
* [Data Views](https://docs.welkinhealth.com/care/data-views/data-views) – viewing data in Care
* [Custom Data Types](/designer/custom-data-types/custom-data-types) – CDT fundamentals
* [CDT Designer](/designer/custom-data-types/custom-data-types-cdt-designer) – CDT configuration
* [Patient Profile](https://docs.welkinhealth.com/care/patients/patient-profile) – Care-side patient view
# Enable Patient Delete
## Overview
By default, patient records cannot be deleted from Welkin. This protects against accidental or unauthorized data loss. The Designer includes a setting to enable patient deletion for your environment – which should only be activated after careful consideration of your data retention requirements and compliance obligations.
***
## Enabling Patient Delete
1. In the Designer, navigate to **Settings** or **Patient Settings**.
2. Locate the **Enable Patient Delete** toggle.
3. Enable the toggle.
4. Create a draft and publish the change.
Once enabled, users with the appropriate permissions can delete patient records from the Care Portal.
***
## Permissions Required
Enabling the setting in the Designer does not automatically allow all users to delete patients. You must also:
1. Go to **Security Policies** in the Designer.
2. Grant the **Patient Delete** permission to the appropriate roles.
3. Publish the policy change.
Only users with both the role permission and security policy access will be able to delete patient records.
***
## Important Considerations
* **This action is irreversible.** Deleted patient records cannot be recovered from the Welkin UI. Ensure your organization has an appropriate backup or data retention process.
* **Compliance review** – before enabling patient delete, consult with your compliance team regarding HIPAA, state regulations, and your organization's data retention policies.
* **Audit trail** – all patient delete actions are recorded in the Data Audit log. See [Data Audit](https://docs.welkinhealth.com/admin#data-audit).
***
## Disabling Patient Delete
To disable patient deletion again:
1. Navigate to **Settings** in the Designer.
2. Turn off the **Enable Patient Delete** toggle.
3. Publish the change.
# How to Create Navigation Layouts
## Overview
Navigation layouts in the Designer control the structure of the left-hand sidebar menu in the Care Portal. Each role can have a different navigation layout – allowing you to show only the pages and features relevant to each user type.
***
## How Navigation Layouts Work
* A navigation layout is a menu configuration tied to one or more roles.
* It defines which items appear in the Care Portal sidebar and in what order.
* Items that are not included in the layout are not visible to users with that role.
***
## Creating a Navigation Layout
1. In the Designer, navigate to **Navigation** or **Navigation Layouts**.
2. Click **+ Add Layout** or create a new draft.
3. Enter a **Name** for the layout.
4. Select the **roles** this layout applies to.
5. Add **menu items** from the available list:
* Homepage
* Patients / My Patients
* Calendar
* Inbox
* Tasks
* Reports / Insights
* Custom pages or links
6. Set the **order** of items by dragging them into position.
7. Save and publish.
***
## Adding the Inbox to Navigation
The Inbox must be explicitly added to the navigation layout for each role that requires access. See [Inbox](https://docs.welkinhealth.com/care/communication/inbox#the-designer-portal) for permission requirements.
***
## Role-Specific Layouts
Different roles typically have different navigation needs:
* **Care Managers** – Patients, Calendar, Inbox, Tasks
* **Supervisors** – Patients (all), Insights, Reports
* **Administrators** – limited Care Portal access, primarily administrative views
***
## Publishing
Create a draft in the Designer and publish to apply the navigation layout to the Care Portal.
# Customize Action Bar
## Overview
The Action Bar is the set of quick-action buttons displayed in the patient profile in the Care Portal. It allows care team members to perform common actions – like creating an encounter, sending a message, or adding a task – directly from the patient view without navigating away. You can customize which actions appear in the Action Bar for each role.
***
## Default Action Bar Items
By default, the Action Bar may include:
* **New Encounter** – start a new encounter with the patient
* **Send Message** – open the communication composer
* **Add Task** – create a task for this patient
* **Enroll in Program** – add the patient to a care program
***
## Customizing the Action Bar
1. In the Designer, navigate to **Action Bar** or **Customize Action Bar**.
2. Select the role or profile you want to customize.
3. Add or remove actions from the available list.
4. Set the display order.
5. Save and publish.
***
## Role-Based Customization
The Action Bar can be configured differently per role. For example:
* Care Managers see "Send Message" and "New Encounter"
* Supervisors see "View Audit" and "Change Region"
* Read-only users have no action bar items
***
## Publishing
Create a draft in the Designer and publish to apply Action Bar changes to the Care Portal.
# Custom Data Types
## Overview
Custom Data Types (CDTs) are configurable data structures in Welkin that allow organizations to capture and store structured patient information beyond the default fields. CDTs are the foundation for clinical data collection – from vitals and lab values to custom assessments and medication records.
## What CDTs Enable
With CDTs, your organization can:
* Define custom fields with specific data types (text, number, date, boolean, dropdown, etc.)
* Create repeatable data entries (e.g., multiple blood pressure readings over time)
* Build structured data panels within patient profiles
* Power charts, graphs, and data views based on CDT values
* Trigger automations based on CDT field values
* Export CDT data via API or reporting tools
## CDT Structure
A CDT consists of:
* **Name** – the CDT's identifier (used in conditions and automations)
* **Display Name** – the label shown to care team members in the Care Portal
* **Fields** – the individual data points within the CDT (e.g., systolic, diastolic, recorded date for a blood pressure CDT)
* **Record settings** – whether the CDT stores a single record per patient or multiple records over time
## Common CDT Use Cases
* **Vitals** – height, weight, BMI, blood pressure, heart rate
* **Lab results** – HbA1c, cholesterol, creatinine, with reference ranges
* **Medications** – drug name, dose, frequency, prescriber, start/stop dates
* **Risk scores** – calculated scores from assessments stored as structured data
* **Social determinants** – housing status, food security, transportation access
* **Custom intake data** – any patient attribute not covered by the default data model
## Creating and Managing CDTs
CDTs are created and configured in the CDT Designer within the Welkin Designer portal. For step-by-step instructions, see [CDT Designer](/designer/custom-data-types/custom-data-types-cdt-designer).
For field type reference, see [Custom Field Types](/designer/custom-data-types/custom-field-types).
***
## Related Topics
* [CDT Designer](/designer/custom-data-types/custom-data-types-cdt-designer) – step-by-step CDT configuration
* [CDT Configuration](/designer/custom-data-types/cdt-configuration) – advanced CDT settings
* [Custom Field Types](/designer/custom-data-types/custom-field-types) – field type reference
* [Create Formulaic CDT Fields](/designer/custom-data-types/create-formulaic-custom-data-type-fields) – calculated fields
* [Patient Data View](/designer/programs-and-profiles/patient-data-view) – viewing CDT data in Care
* [Data Views](https://docs.welkinhealth.com/care/data-views/data-views) – Care-side data visualization
# CDT Designer
## Overview
Custom Data Types (also known as CDTs) are user-defined fields and objects used to capture and store patient information within Welkin. CDTs form the foundation of your data model, allowing you to record clinical assessments, outcomes, custom metrics, and any other organization-specific information needed for care management.
CDTs are built and configured within Designer under the **Custom Data** > **Data Types** section, making them available throughout your Welkin environment for use in assessments, data views, automations, charts, and more.
## Key Concepts
* **CDT** – A container that holds related data fields (analogous to a database table)
* **CDTF** – A Custom Data Type Field; an individual field within a CDT (analogous to a table column)
* **Field Type** – The data type of the field (text, integer, float, list, formula, etc.)
* **Naming Convention** – Automatic prefix applied to all CDTs based on your organization's naming conventions (typically "cdt-")
## Creating a Custom Data Type
### Step 1: Start a New CDT
1. Log into Designer
2. Navigate to **Custom Data** > **Data Types** from the left sidebar
3. Click **+ New** in the upper right corner
4. Enter a **Name** for the CDT using:
* Lowercase letters
* Numbers
* Underscores (\_) or hyphens (-)
* No spaces or special characters
**Example names:**
* `patient-vital-signs`
* `depression-screening`
* `medication-adherence`
**Note:** The system automatically generates a naming convention prefix (e.g., "cdt-") that you can use or remove based on your configuration.
### Step 2: Create Data Fields (CDTFs)
Click **+ Data Field** to add individual fields to your CDT. For each field, configure:
#### Field Configuration
1. **Name** – Field identifier (same naming rules as CDT)
* Example: `systolic_pressure`, `bmi_score`, `patient_name`
2. **Type** – Select the data type:
* **Text** – Free-form text input
* **Long Text** – Extended text areas
* **Integer** – Whole numbers
* **Float** – Decimal numbers
* **Boolean** – True/False or Yes/No values
* **Date** – Date selector
* **DateTime** – Date and time combination
* **List** – Single-select dropdown options
* **Multi-Select List** – Multiple-select options
* **Formula** – Calculated field based on other fields
* **Dictionary** – Reference to shared terminology/definitions
* **Profile** – Reference to patient or contact profiles
* **Attachment** – File uploads
* **Custom Type** – Reference to another CDT
3. **Options** (for List/Multi-Select types):
* Enter each option as a separate line
* Optionally assign numeric values (useful for scoring)
* Set colors for visual differentiation if desired
4. **Required** – Check if this field must be completed
5. **PHI (Protected Health Information)** – Check if field contains sensitive health data
### Step 3: Add Additional Fields
Continue clicking **+ Data Field** to add more fields as needed. Common patterns:
**Vital Signs CDT might include:**
* systolic\_pressure (Integer)
* diastolic\_pressure (Integer)
* heart\_rate (Integer)
* temperature (Float)
* measurement\_date (Date)
**Assessment CDT might include:**
* question\_response (List)
* explanation\_text (Long Text)
* score (Integer)
* assessment\_date (Date)
### Step 4: Configure Field Relationships (Optional)
For more advanced configurations:
1. **Link to Custom Field Types** – If you've created reusable field templates, select them here to maintain consistency across CDTs
2. **Set PHI Status** – Mark fields containing personally identifiable or sensitive health information
3. **Add Descriptions** – Document field purpose for your team
### Step 5: Save and Publish
1. Click **Save** to save your CDT in draft form
2. Click **Publish** to make the CDT and its fields available for use throughout Welkin:
* In Assessments and Forms
* In Data Views
* In Charts and Graphs
* In Automations and Workflows
* In Patient Profiles
## Using CDTs in Your Configuration
Once published, CDTs can be:
### In Assessments
* Add CDTF questions to assessment templates
* Reference fields in conditional logic
* Display calculated scores
### In Data Views
* Show key patient metrics in profile summaries
* Display historical data trends
* Group related information by CDT
### In Charts & Graphs
* Visualize numeric data over time
* Create line graphs, bar charts, or pie charts
* Track patient progress on key metrics
### In Automations
* Trigger actions when CDT fields are updated
* Use field values in conditional logic
* Reference field data in message templates
### In Security Policies
* Control CRUD (Create, Read, Update, Delete) access per role
* Restrict sensitive fields based on user permissions
## Best Practices
1. **Plan Your Structure** – Design CDTs to group logically related fields
2. **Use Naming Conventions** – Apply consistent naming for fields and CDTs across your environment
3. **Document Purpose** – Include descriptions noting what each CDT and field represents
4. **Minimize Redundancy** – Avoid creating duplicate fields in multiple CDTs when one shared CDT would work
5. **Consider Reusability** – Create Custom Field Types for fields you'll use in multiple CDTs
6. **Test Before Publishing** – Create test assessments using your CDTs to verify data capture
7. **Review Security** – Ensure appropriate security policies control access to sensitive health data
## CDT Naming Conventions
Welkin supports flexible naming through the **Naming Conventions** configuration in Designer. Common patterns:
* **Prefix-based:** `cdt-vital-signs`, `cdt-depression-screening`
* **Abbreviation-based:** `vs-systolic`, `ds-score`
* **No prefix:** Direct names like `vital-signs`, `depression-screening`
Configure your organization's preferred pattern in the Designer settings.
## Related Topics
* [Designer: Feature Overview – Custom Data Types](/designer/custom-data-types/custom-data-types) – Overview of CDT capabilities
* [Create Formulaic Custom Data Type Fields](/designer/custom-data-types/create-formulaic-custom-data-type-fields) – Building calculated fields
* [Custom Field Types](/designer/custom-data-types/custom-field-types) – Creating reusable field templates
* [How to Create an Assessment or Form Template](/designer/documents-and-assessments/how-to-create-an-assessment-or-form-template) – Using CDTs in forms
* [Welkin Naming Conventions Dictionary](/designer/terminology-and-help/welkin-naming-conventions-dictionary) – Naming standards
* [Configuring Security Policies](/designer/security/configuring-security-policies) – Controlling CDT access
# CDT Configuration
Custom Data Types (CDTs) are one of the cornerstones for customization in Welkin, allowing for the entry of data points used throughout the platform.
## What are Custom Data Types?
CDTs allow for the entry of data points that may be used throughout Welkin. When creating a new CDT, think of the CDT name as the folder name and the data fields created within it (CDTFs) as sub-categories of that folder. CDTs are created in Designer under **Custom Data → Data Types**.
Click **+New** in the Data Types screen. From here, enter the CDT name (the "folder name") and then enter a data field name (the "sub-folder"). Select the type of data the field will contain from the dropdown — many options are available. Certain selections will reveal additional options for that field. For example, selecting **Boolean** will add a field asking whether it should be a radio button or checkbox.
Continue adding fields by clicking **+ Data Field** at the bottom of the previous field.
## Using CDTs
Once created, CDTs can be used across Welkin. The most common use is in Forms and Assessments — a question is entered, a Data Type is selected from the dropdown, and then the specific Data Field is chosen. That field will record the patient's answer during the assessment.
For more information on creating Assessments, see [Create an Assessment or Form Template](/designer/documents-and-assessments/how-to-create-an-assessment-or-form-template).
## Considerations
* When a CDT is referenced in an Assessment, it writes a value to **all CDTFs** regardless of which are surfaced in the assessment
* A Data View for a CDT can only surface values from one CDT — multiple CDTs cannot be combined into a single Data View
* Creating any CDTs will require updates to your current Security Policies
* **CDT names cannot be changed once created**
* **CDTF settings cannot be changed after creation** (e.g., a list type field cannot later be changed to free text)
* Think through the above considerations and the end result of the data collected before creating CDTs
## Formulas
Formulas are a specific CDTF type that calculates values based on other CDTFs within the same CDT. For example, a patient Assessment that records height and weight into two CDTFs can use a third Formula CDTF to calculate and store BMI, which can then be displayed in a Data View.
For more information, see [Create Formulaic Custom Data Type Fields](/designer/custom-data-types/create-formulaic-custom-data-type-fields).
***
More Questions? Contact or your Implementation/CSM directly.
# Create Formulaic CDT Fields
## Overview
Mathematical expressions and formulas can be utilized within Custom Data Type Fields (CDTFs) to automatically calculate values or combine data from multiple fields. Formulaic fields can derive answers from two or more fields, perform mathematical calculations, or concatenate string values into a single result. These fields are useful for computing derived metrics, combining patient information, or calculating scores based on assessment answers.
Formulaic CDTFs can be associated with multiple Data Views, Assessments, Charts and Graphs throughout your Welkin environment.
## Prerequisites
Before creating a formulaic custom data type field:
1. Create a Custom Data Type (CDT) in Designer. For detailed instructions, see the [Custom Data Types (CDT): Designer](/designer/custom-data-types/custom-data-types-cdt-designer) guide.
2. Ensure you have the necessary data fields already created within the CDT that will be referenced in the formula.
## Creating a Formulaic Field
### Step 1: Set Up the Base CDT
1. Log into Designer
2. Navigate to **Custom Data** > **Data Types**
3. Create or open an existing CDT
4. Click **+ Data Field** to add a new field to your CDT
### Step 2: Configure the Field Type
When creating a formulaic field, set the field configuration as follows:
1. Enter a **Name** for the field (lowercase, numbers, underscores, or hyphens)
2. Set the **Type** to one of the following:
* **Formula** – for mathematical calculations
* **Integer** or **Float** – for numeric results
* **Text** – for string concatenation results
### Step 3: Create List Options with Numeric Values
If using a List field type that will feed into formulas:
1. Set **Type** to "List"
2. Set **Value Type** to "Integer" or "Float" to assign numeric values to each option
3. In the **Options field**, add your answer choices and their corresponding point values
**Example:**
* Question: "Did the patient meet their goal?"
* Options:
* Yes = 2 points
* No = 1 point
* Not assessed = 0 points
### Step 4: Define the Formula Expression
1. Select **Type** = "Formula"
2. In the formula editor, you can:
* **Reference fields** from the same CDT using field variable syntax
* **Perform calculations** using operators (+, -, \*, /, etc.)
* **Combine strings** by referencing text fields
**Formula Examples:**
* **BMI Calculation:** `(weight_field / (height_field * height_field)) * 703`
* **Age Calculation:** Calculate years between two dates
* **Score Combination:** `field1_value + field2_value + field3_value`
* **String Concatenation:** `first_name_field + " " + last_name_field`
### Step 5: Publish the Configuration
1. Click **Save** to save your changes
2. Click **Publish** to make the formulaic field available in Care and other visual components
3. The formula will automatically calculate values whenever the referenced fields are updated
## Using Formulaic Fields in Assessments and Data Views
Once your formulaic CDTF is created and published, you can:
* **Add to Assessments** – Include the formulaic field in assessment forms to display calculated results
* **Display in Charts & Graphs** – Visualize calculated data over time in line graphs, bar graphs, or pie charts
* **Reference in Automations** – Trigger automations based on calculated values
* **Show in Patient Data Views** – Display derived metrics in the Care portal patient profile
## Best Practices
* **Test formulas thoroughly** before publishing to ensure accuracy
* **Document formula logic** in your naming conventions for team clarity
* **Use Integer or Float types** for numeric calculations to ensure proper math operations
* **Reference only fields** that will consistently have values to avoid null calculation errors
* **Keep formulas simple** when possible for better performance and easier maintenance
* **Consider decimal precision** when setting Float field types for currency or percentages
## Limitations and Considerations
* Formulas are recalculated automatically when source fields are updated
* Circular references (where Field A depends on Field B, and Field B depends on Field A) are not supported
* Formulas execute synchronously; very complex calculations may impact performance
* Formula fields cannot reference fields from different CDTs (cross-CDT references are not supported)
## Related Topics
* [Custom Data Types (CDT): Designer](/designer/custom-data-types/custom-data-types-cdt-designer) – Creating and managing CDTs
* [Custom Field Types](/designer/custom-data-types/custom-field-types) – Reusable field type templates
* [Charts & Graphs: How to Configure](/designer/charts-and-graphs/charts-graphs-how-to-configure) – Displaying calculated data visually
* [How to Add Conditionality to Assessments](/designer/documents-and-assessments/how-to-add-conditionality-to-assessments) – Conditional logic in forms
* [Designer: Feature Overview – Custom Data Types](/designer/custom-data-types/custom-data-types) – General CDT overview
# Custom Field Types
## Overview
Custom Field Types (CFTs) are reusable field templates that help streamline the creation of Custom Data Types (CDTs) when you need to use the same field configuration across multiple CDTs. Instead of manually recreating the same field setup repeatedly, you can define a Custom Field Type once and then apply it to as many CDTs as needed.
Custom Field Types are particularly useful for maintaining consistency across your data model and reducing configuration time.
## Key Benefits
* **Reusability** – Define once, use in many CDTs
* **Consistency** – Ensure the same field types and options across your environment
* **Efficiency** – Eliminate duplicate data entry
* **Maintenance** – Update field definitions in one place
* **Examples**:
* A "Yes/No" field type with consistent options used in 10 different assessments
* A "Pain Scale" list (0-10) used in multiple clinical CDTs
* A medication dosage formula used across medication-related CDTs
* A "Priority Level" list with colors and values
## When to Use Custom Field Types
Use Custom Field Types when you have:
* **List fields** with the same predefined options (e.g., "Yes/No", "Low/Medium/High", "Never/Rarely/Sometimes/Always")
* **Formula fields** with the same calculation (e.g., BMI calculation, age from DOB)
* **URL fields** with the same validation or format
* **Select fields** with the same set of choices that appear in multiple assessments
* **Scoring scales** (e.g., Likert scales) that appear in multiple assessment tools
## Creating a Custom Field Type
### Step 1: Access Custom Field Types in Designer
1. Sign into Designer
2. Click **Create Draft** to start a new configuration draft
3. Navigate to **Custom Data** > **Custom Field Types** from the left sidebar
4. Click **+ New** in the upper right corner
### Step 2: Name Your Custom Field Type
Enter the following information:
1. **Title** – User-friendly name
* Example: "Pain Severity Scale", "Yes/No Response"
* This appears in dropdown lists when creating CDTs
2. **Name** – Internal system name (lowercase, numbers, underscores, hyphens)
* Auto-populates from Title but can be customized
* Example: `pain-severity-scale`
3. **Description** (optional) – What this field type is for
* Example: "0-10 pain rating scale used in chronic pain assessments"
### Step 3: Select the Field Type and Configure Options
Choose the type of field this Custom Field Type represents:
#### List Field Type
**Use for:** Single-select dropdown options
**Configuration:**
1. Set **Type** = "List"
2. Set **Value Type** = (choose option):
* **String** – for text-based options
* **Integer** – for numeric values (useful for scoring)
* **Float** – for decimal values
* **Boolean** – for true/false
3. **Add Options** – Enter each option as a separate line
**Example: "Yes/No with Integer Values"**
```
Yes = 1
No = 0
Unknown = -1
```
**Example: "Likert Scale"**
```
Strongly Disagree = 1
Disagree = 2
Neutral = 3
Agree = 4
Strongly Agree = 5
```
**Example: "Pain Level"**
```
None = 0
Mild = 1
Moderate = 2
Severe = 3
Unbearable = 4
```
#### Multi-Select List Field Type
**Use for:** Multiple-select options where users can choose more than one
**Configuration:**
1. Set **Type** = "Multi-Select List"
2. Set **Value Type** = String or Integer
3. **Add Options** – Enter each option as a separate line
**Example: "Symptoms Checklist"**
```
Fatigue
Headache
Dizziness
Nausea
```
#### Formula Field Type
**Use for:** Calculated values based on mathematical expressions
**Configuration:**
1. Set **Type** = "Formula"
2. **Enter the Formula Expression**
* Use placeholder syntax like `{{field1}}` and `{{field2}}`
* Example: `({{weight}}/{{height}}) * 703` for BMI
3. Set **Return Type** = Integer or Float
**Example: "Age Calculation from DOB"**
```
Formula: (current_date - {{date_of_birth}}) / 365.25
Return Type: Integer
```
#### Text Field Types
**Use for:** Standard text, long text, email, phone, or URL formats
**Configuration:**
1. Set **Type** = "Text", "Long Text", "Email", "Phone Number", or "URL"
2. Set any additional validation rules if available
3. Add placeholder or example text if desired
**Example: "Email Address"**
```
Type: Email
Validation: Standard email format
```
### Step 4: Set Additional Properties
Configure any additional field properties:
1. **Required** – Check if this field must always be filled when used
2. **PHI (Protected Health Information)** – Check if this field contains sensitive data
3. **Help Text** (optional) – Guidance for users completing this field
4. **Placeholder Text** (optional) – Example text shown in empty field
### Step 5: Save and Publish
1. Click **Save** to save your Custom Field Type
2. Click **Publish** to make it available for use when creating CDTs
## Using Custom Field Types in CDTs
### When Creating a CDT
1. In Designer, create or edit a Custom Data Type
2. Click **+ Data Field**
3. Look for a dropdown or selector that shows **"Custom Field Types"**
4. Select your newly created Custom Field Type
5. The field automatically inherits:
* All options/values
* Data type configuration
* Required/PHI status (if set)
* Help text and placeholders
6. You can optionally override specific properties if needed
7. Click **Save** to add the field
**Example Workflow:**
Using "Pain Severity Scale" Custom Field Type:
1. Create CDT "pain\_assessment"
2. Click + Data Field
3. Select **Type** = "Custom Field Type" → "Pain Severity Scale"
4. Name the field "pain\_rating"
5. Field automatically gets 0-4 scale with "None/Mild/Moderate/Severe/Unbearable"
6. Save
7. Repeat in another CDT "migraine\_tracking" → also gets the same scale
## Benefits in Practice
### Before Custom Field Types
Creating assessment with 5 questions on a Likert scale:
* Manually enter "Strongly Disagree, Disagree, Neutral, Agree, Strongly Agree" five times
* Each field takes 2-3 minutes
* Total: 10-15 minutes, prone to typos
### After Custom Field Types
Creating assessment with 5 questions on a Likert scale:
* Select "Likert Scale" Custom Field Type five times
* Field auto-populates all options
* Total: 1-2 minutes, perfect consistency
## Best Practices
1. **Clear Naming** – Use names that describe what the field represents
* ✓ Good: "Yes/No Response", "Pain Severity Scale", "Likert Scale 5-Point"
* ✗ Poor: "List1", "Field Type A", "cft\_misc"
2. **Document Purpose** – Include descriptions explaining when to use
* "Use for consent/agreement questions"
* "Depression screening severity (PHQ-9 compatible)"
3. **Consistent Options** – Ensure option values match across uses
* If "Likert Scale" always uses 1-5, don't create variants
* Create separate types for different scales
4. **Value Assignment** – Always assign numeric values to scored lists
* Makes scoring and calculations easier
* Ensures consistency in automations
5. **Regular Review** – Periodically audit Custom Field Types
* Remove unused types
* Consolidate similar types
* Update if standards change (e.g., new assessment scales)
6. **Naming Convention** – Follow your organization's naming standards consistently
7. **Version Control** – Document which assessment versions use which CFTs
## Limitations
* Custom Field Types cannot be modified after use in a CDT without affecting existing data
* If you need to change a CFT, you may need to create a new version
* Not all field types can be made into Custom Field Types (some require CDT-specific configuration)
## Examples of Commonly Used Custom Field Types
### Healthcare Examples
1. **Likert Scales** – 5-point agreement scales used in many assessments
2. **Yes/No Fields** – Binary responses in screening tools
3. **Pain Rating Scale** – 0-10 or 0-4 numeric scales
4. **Risk Level** – Low/Medium/High for risk assessments
5. **Frequency Scales** – Never/Rarely/Sometimes/Often/Always
6. **Outcome Measures** – Standardized scales like PHQ-9, GAD-7 response options
### Operational Examples
1. **Priority Levels** – Critical/High/Medium/Low for task management
2. **Status Options** – Active/Inactive/Pending/Completed
3. **Department Names** – Reference to standard departments
4. **Location/Facility List** – Standard clinic or facility names
## Related Topics
* [Custom Data Types (CDT): Designer](/designer/custom-data-types/custom-data-types-cdt-designer) – Creating CDTs that use CFTs
* [Create Formulaic Custom Data Type Fields](/designer/custom-data-types/create-formulaic-custom-data-type-fields) – Formula field types
* [How to Create an Assessment or Form Template](/designer/documents-and-assessments/how-to-create-an-assessment-or-form-template) – Using CDTs with CFTs in forms
* [Designer: How to Configure Scored Assessments](/designer/documents-and-assessments/designer-how-to-configure-scored-assessments) – Scoring with list options
* [Welkin Naming Conventions Dictionary](/designer/terminology-and-help/welkin-naming-conventions-dictionary) – Naming standards
# Configure Document Types
## Overview
Document Types in Welkin are categorization templates that help organize and identify documents uploaded into patient records. By configuring Document Types, you create a standardized taxonomy for document management, making it easier for care team members to search, filter, and locate specific documents within a patient's chart.
Examples of Document Types might include: Lab Results, Discharge Summary, Insurance Card, Referral Letter, or X-Ray Reports. Each Document Type can have additional data fields for subcategorization or metadata.
## Key Benefits
* **Organization** – Standardized categories reduce search time
* **Consistency** – Team members use same document naming across patients
* **Searchability** – Filter charts by document type
* **Workflow Efficiency** – Quickly find the right documents when needed
* **Metadata Capture** – Add custom fields (notes, subcategories, dates) to documents
* **Security** – Apply security policies to specific document types if needed
## Prerequisites
1. You have access to Designer with appropriate permissions
2. You understand your organization's document management needs
3. You've identified the main document categories you'll need
## Step-by-Step: Create Document Types
### Step 1: Create a New Draft in Designer
1. Log into Designer
2. Click **Create Draft** to begin a new configuration draft
3. You're now in draft mode and can make changes
### Step 2: Access Document Types Configuration
1. On the left sidebar, navigate to **Custom Data** section
2. Find and click on **Document Types**
3. You should see a list of existing document types (if any)
4. Click **+ New** to create a new document type
### Step 3: Enter Basic Document Type Information
Fill in the required fields:
#### Title
* **What it is:** Display name shown to care team and in patient charts
* **Example names:**
* "Lab Results"
* "Discharge Summary"
* "Imaging Report"
* "Referral Letter"
* "Insurance Documentation"
* "Progress Note"
* **Best practice:** Use clear, professional terms that your team understands
#### Name
* **What it is:** Internal system name (lowercase, numbers, underscores, hyphens)
* **Auto-populated:** Field auto-generates from Title but can be customized
* **Example names:**
* `lab-results`
* `discharge-summary`
* `imaging-report`
* `referral-letter`
* `insurance-docs`
### Step 4: Add Custom Data Fields (Optional)
Document Types can include additional fields to capture metadata:
#### Adding Fields
1. Click **+ Add Data Field** or **+ New Field**
2. For each field, configure:
* **Field Name** – Name visible to users (e.g., "Lab Category")
* **Field Type** – Type of data:
* **Text** – Free-form text (e.g., "Notes about document")
* **Long Text** – Multi-line text for detailed notes
* **List** – Dropdown options (e.g., "Category" with Blood Work / Imaging / Pathology)
* **Date** – Date field (e.g., "Date of Service")
* **Boolean** – Yes/No checkbox (e.g., "Requires Follow-up")
* **Integer** – Numeric value (e.g., "Page Count")
3. **Required** – Check if field must be filled when uploading document
4. **Options** (for List fields) – Enter available selections
#### Example: Lab Results Document Type
```
Document Type: Lab Results
Fields:
1. Lab Category (List - Required)
Options: Chemistry / Hematology / Microbiology / Immunology
2. Lab Date (Date)
3. Result Status (List)
Options: Preliminary / Final / Corrected
4. Critical Values (Boolean)
Help text: "Check if any critical lab values present"
5. Provider Notification (Text - Optional)
Help text: "Document how provider was notified"
```
#### Example: Insurance Documentation Type
```
Document Type: Insurance Documentation
Fields:
1. Document Category (List - Required)
Options: Insurance Card / Policy Details / EOB / Verification Letter
2. Insurance Company (Text)
3. Policy Number (Text)
4. Effective Date (Date)
5. Notes (Long Text - Optional)
```
### Step 5: Save Your Document Type
1. After configuring fields, click **Save** to save in draft
2. Document Type is saved but not yet available in Care
### Step 6: Complete Security Policy Configuration
**Important:** Document Types need security policy configuration to be available in Care.
1. Still in your draft, navigate to **Access Control** > **Security Policies** in left sidebar
2. Find or create a Security Policy that applies to Document Types
3. In the policy, ensure the Document Type you just created is included with appropriate permissions:
* **Create** – Who can upload documents of this type
* **Read** – Who can view documents of this type
* **Update** – Who can edit document metadata
* **Delete** – Who can delete documents of this type
For detailed security policy configuration, see [Configuring Security Policies](/designer/security/configuring-security-policies).
### Step 7: Publish Your Configuration
1. Review all changes made in your draft
2. Click **Publish** to activate the new Document Type
3. Document Type is now available in Care for document uploads
## Using Document Types in Care
### Uploading Documents
Once configured and published, care team members can:
1. In patient chart, navigate to **Documents** section
2. Click **Upload Document** or **+ New Document**
3. Select the **Document Type** from dropdown (uses Title you configured)
4. Complete any required fields you defined
5. Select or upload the document file
6. Click **Save** to upload
### Searching/Filtering Documents
Care team can then:
1. View patient's document list filtered by Document Type
2. Use Document Type filter to find specific categories
3. Search within metadata fields you created
4. Sort documents by type or date
## Document Type Organization Strategies
### Strategy 1: By Document Source
Group documents by where they come from:
* Lab Results
* Imaging Reports
* Pharmacy Records
* Insurance Documents
* External Hospital Records
### Strategy 2: By Clinical Category
Group documents by clinical area:
* Cardiology Reports
* Psychiatry Notes
* Surgical Reports
* Pathology Results
* Radiology Imaging
### Strategy 3: By Administrative Category
Separate clinical from administrative:
* Clinical Notes
* Test Results
* Administrative (Insurance/ID)
* Consent Forms
* Legal Documents
### Strategy 4: By Care Workflow
Organize around your care processes:
* Initial Intake
* Ongoing Assessment
* Discharge
* Follow-up
## Best Practices
1. **Keep List Short** – Limit to 15-20 document types; too many causes confusion
2. **Clear Names** – Use terms your team naturally uses (avoid jargon users don't recognize)
3. **Avoid Duplication** – Don't create similar document types that could overlap
4. **Organize Logically** – Order types in a way that matches workflow
5. **Use Subcategories** – Use List fields to sub-categorize within a document type rather than creating many parent types
6. **Test Before Publishing** – Have team review proposed document types
7. **Train Users** – Educate care team on which type to select for each document
8. **Include Metadata** – Use optional fields for important tracking information
9. **Regular Review** – Periodically check if document types still match your needs
10. **Document Definitions** – Keep written guidance on which documents go in which type
## Example: Complete Document Type Configuration
```
Document Type: Discharge Summary
Title: Discharge Summary
Name: discharge-summary
Fields:
1. Discharge Type (List - Required)
- Hospital Discharge
- Clinic Closure
- Transfer to Other Care
- AMA (Against Medical Advice)
2. Discharge Date (Date - Required)
3. Primary Diagnosis ICD Code (Text)
4. Medications at Discharge (Long Text)
5. Follow-up Needed (Boolean)
Help: "Check if patient requires follow-up appointments"
6. Follow-up Instructions (Long Text - appears if "Follow-up Needed" = Yes)
7. Discharging Provider (Text)
Security Policy:
- Care Team Roles: Can Create, Read, Update, Delete
- Admin Role: Can Create, Read, Update, Delete
- Patient Facing: Read Only
```
## Troubleshooting
### Document Type Not Appearing in Care
**Problem:** Document Type is created but doesn't appear in the upload dropdown
**Solutions:**
* Verify Document Type was published (not just saved in draft)
* Check security policy – Document Type must be included with "Create" permission
* Confirm user's role has permission to create this document type
* Refresh browser cache
* Verify Document Type isn't restricted to specific users/roles
### Required Fields Not Enforcing
**Problem:** Can upload documents without filling required fields
**Solutions:**
* Verify field is marked as "Required" in Document Type configuration
* Publish a new version of configuration
* Clear browser cache
* Test with a different user account
### Field Not Showing When Uploading
**Problem:** Field is defined but doesn't appear in upload form
**Solutions:**
* Check field is not hidden or restricted in security policy
* Verify Document Type was published after field was added
* Confirm field is marked with proper permissions in security policy
* Test with admin account to verify field exists
## Related Topics
* [Configuring Security Policies](/designer/security/configuring-security-policies) – Setting permissions for document types
* [Custom Data Types (CDT): Designer](/designer/custom-data-types/custom-data-types-cdt-designer) – Creating custom fields for documents
* [Designer: Feature Overview – Security Policies](/designer/security/setup-security-policies) – Security policy overview
* [Patient Profile Overview](https://docs.welkinhealth.com/care/patients/patient-profile-overview) – Viewing documents in Care
* [Welkin Naming Conventions Dictionary](/designer/terminology-and-help/welkin-naming-conventions-dictionary) – Naming standards
# Add Conditionality to Assessments
## Overview
Welkin Health allows you to add conditional logic to assessments, enabling fields to be shown or hidden based on responses to other questions. Conditional fields improve user experience by displaying only relevant questions and reducing assessment length for users who don't meet certain criteria.
For example, you might show a "Please specify" text field only if a user selects "Other" from a list, or display allergy questions only if the patient answers "Yes" to having allergies.
## Key Concepts
* **Conditional Statement** – A rule that shows/hides a field based on another field's value
* **Trigger Field** – The question whose response determines visibility
* **Conditional Field** – The question that appears/disappears based on the trigger
* **Condition Logic** – The rule that evaluates the trigger field (e.g., "equals Yes", "contains 'Other'")
* **Single CDT Conditions** – Most common; conditions within one CDT
* **Multi-CDT Conditions** – Advanced; conditions across multiple CDTs
## Building Blocks for Conditionality
### Step 1: Create CDTs and CDTFs for Your Questions
Before adding conditions, you need:
1. **Trigger Field CDTF** – The field whose response triggers the condition
* Type: Usually "List" (single-select) or "Multi-Select List"
* Options: Must include a value that will trigger the condition
* Example: A "Yes/No" list field or "Other" option in a dropdown
2. **Conditional Field CDTF** – The field that appears when condition is met
* Type: Can be any field type (text, numeric, date, etc.)
* Example: "Please specify" text area field
**Simple Example Structure:**
```
CDT: medical-history
- has_allergies (List: Yes/No) ← Trigger field
- allergy_details (Long Text) ← Conditional field (shown only if has_allergies="Yes")
```
**Complex Example Structure:**
```
CDT: patient-education
- education_level (List: High School/Some College/Bachelor's/Other) ← Trigger
- other_education (Text) ← Conditional 1 (shown if = "Other")
- college_major (Text) ← Conditional 2 (shown if = "Bachelor's")
- years_of_college (Integer) ← Conditional 3 (shown if = "Some College" OR "Bachelor's")
```
### Step 2: Create the Assessment/Form Template
1. In Designer, navigate to **Visual Components** > **Forms**
2. Create a new assessment or edit an existing one
3. Add the CDTs and fields you created above to the form
4. Arrange them in logical order
5. Save the form (don't publish yet)
### Step 3: Add Conditional Logic to the Assessment
1. In the form editor, locate the **Conditional Logic** section or **Form Rules**
2. Look for a button like **+ Add Condition**, **Add Rule**, or **Conditional Logic**
## Creating a Condition
### Basic Condition Structure
Most conditions follow this pattern:
```
IF [Trigger Field] [Condition Operator] [Value]
THEN Show [Conditional Field]
```
### Condition Configuration
1. **Select the Trigger Field** – Choose which field's response will trigger the condition
* Typically a field that's already visible on the form
* Usually a List or Multi-Select field
2. **Select Condition Operator** – Choose how to evaluate the trigger field:
* **Equals** – Value exactly matches
* **Not Equals** – Value does not match
* **Contains** – Value includes specified text
* **Does Not Contain** – Value does not include text
* **Greater Than** – Value is numerically greater
* **Less Than** – Value is numerically less
* **Is Empty** – Field has no value
* **Is Not Empty** – Field has a value
3. **Enter the Condition Value** – Specify what value triggers the condition:
* Example: If operator is "Equals", enter the specific option (e.g., "Yes", "Other")
* Example: If operator is "Contains", enter the substring to look for
4. **Select Field to Show** – Choose which field appears when condition is true:
* This field will be hidden by default
* It shows only when the condition is met
5. **Save the Condition** – Click **Save** or **Add Condition**
## Practical Examples
### Example 1: Show "Other, Please Specify" Field
**Scenario:** Employment status question with "Other" option that requires explanation
**Trigger Field:** `employment_status` (List: Employed/Unemployed/Self-Employed/Student/Other) **Conditional Field:** `employment_status_other` (Text: "Please describe your employment")
**Condition Configuration:**
```
IF employment_status EQUALS "Other"
THEN Show employment_status_other
```
**Result:**
* Patient sees employment status dropdown
* Selects "Other"
* "Please describe your employment" field appears
* Patient can now enter details
### Example 2: Progressive Disclosure Based on Response
**Scenario:** Medication adherence assessment that asks follow-up questions only for non-adherent patients
**Trigger Field:** `medication_adherence` (List: Always/Most of the Time/Sometimes/Never) **Conditional Fields:**
* `adherence_barriers` (Multi-Select: Cost/Forgetting/Side Effects/Other)
* `adherence_interventions_needed` (Text: "What would help you take your medications as prescribed?")
**Condition Configuration:**
```
Condition 1:
IF medication_adherence EQUALS "Sometimes"
THEN Show adherence_barriers
Condition 2:
IF medication_adherence EQUALS "Never"
THEN Show adherence_barriers
Condition 3:
IF medication_adherence IS NOT EQUAL "Always"
THEN Show adherence_interventions_needed
```
**Result:**
* Patients who always take medications see only one question
* Patients with adherence issues see additional follow-up fields
* Assessment is shorter and more relevant per patient response
### Example 3: Condition with Empty Field Check
**Scenario:** Insurance information only relevant if patient has insurance
**Trigger Field:** `has_insurance` (List: Yes/No) **Conditional Fields:**
* `insurance_provider` (Text)
* `insurance_group_number` (Text)
* `insurance_member_id` (Text)
**Condition Configuration:**
```
IF has_insurance EQUALS "Yes"
THEN Show insurance_provider
AND Show insurance_group_number
AND Show insurance_member_id
```
**Result:**
* If "No": Insurance fields remain hidden
* If "Yes": All three insurance fields appear
### Example 4: Numeric Range Condition
**Scenario:** Show depression severity interventions only for elevated scores
**Trigger Field:** `phq9_score` (Integer: 0-27) **Conditional Field:** `depression_interventions_recommended` (Text)
**Condition Configuration:**
```
IF phq9_score GREATER THAN 10
THEN Show depression_interventions_recommended
```
**Result:**
* Score ≤ 10: No intervention field shown
* Score > 10: Intervention recommendations field appears
## Advanced Conditional Patterns
### Multiple Conditions on One Field
Show a field when ANY of multiple conditions are true (OR logic):
```
IF department EQUALS "Cardiology" OR department EQUALS "Internal Medicine"
THEN Show cardiac_risk_factors
```
### Multiple Conditions (AND Logic)
Show a field only when ALL conditions are true:
```
IF age GREATER THAN 65 AND has_diabetes EQUALS "Yes"
THEN Show diabetic_management_plan
```
### Nested Conditions
Hide/show fields based on multiple levels:
```
IF has_allergies EQUALS "Yes"
THEN Show allergy_type
IF allergy_type EQUALS "Drug Allergy"
THEN Show specific_drug_allergy
```
## Testing Conditional Logic
### Before Publishing
1. **Create a Test Assessment Instance** – As if completing the form
2. **Test Each Condition Path:**
* Select trigger value that shows conditional field → verify it appears
* Select trigger value that hides conditional field → verify it disappears
* Test every option in the trigger field
3. **Test Edge Cases:**
* Empty fields (if condition references empty field)
* Multiple selections (if using Multi-Select)
* Numeric boundaries (if using numeric operators)
### After Publishing
1. Have care team members test in Care app
2. Have patients complete via PFA link
3. Verify conditional fields appear/disappear as expected
4. Check that data is captured correctly when fields are hidden
## Troubleshooting
### Conditional Field Not Showing
**Problem:** Field should appear based on trigger value but doesn't
**Solutions:**
* Verify trigger field value matches condition exactly (case-sensitive)
* Check that conditional field is configured to show on the form
* Ensure condition operator is correct (e.g., "Equals" vs "Contains")
* Test with a different trigger value to isolate issue
* Check browser developer console for JavaScript errors
### Conditional Field Always Showing
**Problem:** Field is always visible regardless of trigger value
**Solutions:**
* Check if field is set as "always visible" in form properties
* Verify conditional logic was saved/published
* Confirm trigger field hasn't been renamed or removed
* Clear browser cache and reload
### Multiple Conditions Not Working Together
**Problem:** Complex conditions with AND/OR logic not behaving correctly
**Solutions:**
* Simplify conditions temporarily to test each separately
* Verify AND/OR logic is configured correctly
* Check parentheses or grouping of conditions
* Test with different trigger values
## Best Practices
1. **Group Related Questions** – Keep trigger and conditional fields close together on form
2. **Clear Labeling** – Use clear question text that explains why conditionals appear
3. **Avoid Complex Nesting** – Keep conditional logic simple when possible
4. **Test Thoroughly** – Test every conditional path before deployment
5. **Document Logic** – Include notes explaining why conditions exist
6. **Consider User Experience** – Don't overuse conditionals; can confuse users if overdone
7. **Mobile Testing** – Test conditionals on mobile devices for responsive behavior
8. **Performance** – Very complex conditional logic may slow form performance
## Limitations
* Conditions typically only reference fields within the same assessment form
* Cross-assessment conditions (based on fields from different assessments) may not be supported
* Conditional logic is evaluated client-side; complex calculations may not be possible
* Some field types may not support conditions
## Related Topics
* [How to Create an Assessment or Form Template](/designer/documents-and-assessments/how-to-create-an-assessment-or-form-template) – Form creation basics
* [Custom Data Types (CDT): Designer](/designer/custom-data-types/custom-data-types-cdt-designer) – Creating fields for conditions
* [Designer: How to Configure Scored Assessments](/designer/documents-and-assessments/designer-how-to-configure-scored-assessments) – Assessment scoring with conditionals
* [Forms: Conditional Logic](/designer/documents-and-assessments/forms-conditional-logic) – Detailed conditional logic reference
* [How to Associate Assessments with Programs](/designer/documents-and-assessments/how-to-associate-assessments-with-programs) – Program-based assessment visibility
# Question Groups in Assessments
Question Groups allow you to organize related questions within an assessment into a named, repeatable set. When completing an assessment, care team members can add multiple instances of the same group — capturing the same structured fields for each entry without duplicating questions in the template.
Common use cases include medication lists (capturing name, dosage, frequency, and route for each medication), family history entries, surgical history, and allergy records.
***
## Key Concepts
* **Question Group** – A named set of questions within an assessment that can be repeated multiple times during a single completion
* **Group Instance** – Each individual repetition added by the care team member during completion
* **Repeating Fields** – The CDT fields within the group, captured separately for each instance
* **Group Ordering** – Instances can be reordered via drag-and-drop during completion
***
## Configuring Question Groups in Designer
### Prerequisites
Before adding a Question Group, ensure:
* The assessment/form template already exists in **Visual Components** > **Forms**
* The CDT fields you want inside the group have been created
* You are working in an active configuration draft
### Step 1: Open the Assessment Template
1. Log into **Designer**
2. Click **Create Draft** or open an existing draft
3. Navigate to **Visual Components** > **Forms**
4. Select the assessment you want to edit, or click **+ New** to create one
### Step 2: Add a Question Group
1. Inside the form editor, click **+ Add Element** or **+ Add Group**
2. Select **Question Group** from the element type options
3. Enter a clear, descriptive name — use a singular noun such as "Medication", "Allergy", or "Family Member"
### Step 3: Add Fields to the Group
1. Inside the group, click **+ Add Field**
2. Select the CDT fields to include in each instance
3. Arrange fields in the order they should appear during completion
### Step 4: Configure Group Settings
* **Group label** – Name displayed above each instance (e.g., "Medication 1", "Medication 2")
* **Conditional logic** – Question Groups support the same show/hide conditions as individual questions
* **Scoring** – Individual fields within a group can contribute to the assessment's overall score
### Step 5: Save and Publish
1. Click **Save** and preview the assessment to verify the group appears correctly
2. Click **Publish** to make the configuration live
***
## Care Team Experience
When a care team member opens an assessment with a Question Group, the group appears as a labeled, collapsible section.
**To add an instance:** complete the fields in the first entry, then click **+ Add Another.**
**To remove an instance:** click the trash icon on the entry.
Each instance is saved as a separate CDT record.
***
## Conditional Logic and Scoring
Question Groups support the same conditional logic available for individual questions. You can show or hide the entire group based on a response elsewhere in the assessment, or show/hide individual fields within the group based on responses inside the same instance.
For scoring, each instance is scored independently and scores are aggregated per the assessment's scoring configuration.
* [Add Conditionality to Assessments](/designer/documents-and-assessments/how-to-add-conditionality-to-assessments)
* [Configure Scored Assessments](/designer/documents-and-assessments/designer-how-to-configure-scored-assessments)
***
## CDT Constraints
Each CDT can only be used in one place within an assessment — either in a regular question or inside a group, but not both.
* If a CDT is already used in a regular question, it cannot be added to a group
* If a CDT is added to a group, it cannot be used in other questions or other groups
**Prepopulation is not supported for groups.** For regular questions, it is possible to set prepopulated answers — including values carried over from a previous assessment. Because groups can contain multiple instances, prepopulation raises logical conflicts and is not currently available for Question Groups. A single CDT cannot be used in both a group and a regular question for this reason.
***
## Editing Assessments with Groups
When editing an assessment that does **not** contain groups, the corresponding CDT records are simply updated in place.
When editing an assessment that **does** contain groups, it is not possible to determine which specific CDT records to update. As a result, Welkin deletes all existing CDT records for the group and creates new ones on save.
This behavior has two important implications:
* **Automations** — any automation triggered by CDT creation or deletion will fire when a grouped assessment is edited. Plan your automation conditions accordingly.
* **Audit log** — the audit log will show entries for the assessment update, followed by deletion entries for each previous group record and creation entries for each new one.
**Example:** An assessment has a group with two existing records. A care team member edits the assessment and adds a third record. The audit log will contain 1 assessment update entry + 2 CDT deletion entries + 3 CDT creation entries.
***
## Best Practices
* Use singular nouns for group names — Welkin labels instances as "Medication 1", "Medication 2", etc.
* Keep groups focused — include only fields that belong to a single logical entry
* Set a minimum instance count of `1` if at least one entry is always expected
* When using automations triggered by CDT creation or deletion, account for the re-creation behavior that occurs on grouped assessment edits
* Always test with 2–3 instances before publishing to confirm data saves correctly
***
## Related Topics
* [How to Create an Assessment or Form Template](/designer/documents-and-assessments/how-to-create-an-assessment-or-form-template) – form creation basics
* [Add Conditionality to Assessments](/designer/documents-and-assessments/how-to-add-conditionality-to-assessments) – conditional show/hide logic
* [Configure Scored Assessments](/designer/documents-and-assessments/designer-how-to-configure-scored-assessments) – scoring configuration
* [Custom Data Types (CDT): Designer](/designer/custom-data-types/custom-data-types-cdt-designer) – creating fields for groups
* [Forms and Assessments](https://docs.welkinhealth.com/care/forms-and-assessments/forms-and-assessments) – Care-side guide
# Visual Components
The Visual Components category of Designer is used to create and configure the majority of the user-facing objects that are present in Care.
There are six categories available (see the individual articles for details on each):
1. **Forms**
2. **PFA Folders** (Patient Facing Assessment Folders)
3. **Charts and Graphs**
4. **Data Views**
5. **Program Summary**
6. **Relationship View** *(Deprecated)*
***
## Forms
The Forms area of Designer is used to create and configure user or patient-facing forms and assessments. Examples include Intake Forms, SOAP Notes, and Patient Satisfaction Forms.
## PFA Folders (Patient Facing Assessment Folders)
PFA Folders are used to create the individual or group of forms that will be sent within a patient SMS or Email for completion by a patient. Here you can configure a color palette for the link a patient sees, messaging once they open and/or complete their forms, and other settings.
## Charts and Graphs
Charts and Graphs are configured to provide users a display of certain patient data collected over time. Line and bar charts can include data such as blood pressure, weight, or values from scored forms and assessments.
## Data Views
Data Views present a user with information collected from a patient through a form, sent by API, or documented directly by a user. Views can be universal for all users or configured for specific role types. Organizations can also choose whether to allow users to directly add or enter information into a patient record, or restrict the data to read-only.
## Program Summary
Program Summary is used to create views of the patient Programs that have been created. Organizations can establish one or more views of their programs and use these to restrict or allow the ability to add or edit programs by their users.
## Relationship View *(Deprecated)*
This area was used to create a visual element to establish a relationship between two patients, such as a husband and wife.
***
More Questions? Contact or your Implementation/CSM for more information.
# Visual Components Dependencies
Welkin Designer offers a number of different data visualization options for both users and patients. The majority of these items will be found under the Designer section called "Visual Components". The options include:
* Forms
* PFA Folders
* Charts and Graphs
* Data Views
* Program Summary
* Relationship View (Deprecated)
**Forms:** The Forms area is where you can create structured data input visualizations for either patients or users. Some examples include:
* Patient Assessment or Patient Satisfaction surveys
* Standard Medical Forms (PHQ9, GAD7, etc)
* SOAP notes
* Referral Forms
To complete Forms, you must have already completed some [CDT](/designer/documents-and-assessments/visual-components-dependencies)s.
To learn more specifics about Forms and form creation, please refer to the Knowledge Base article [here](/designer/documents-and-assessments/visual-components-dependencies).
**PFA Folders:** PFA (Patient Facing Assessment) Folders are used to configure the
# 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) – Detailed variable reference
* [Custom Data Types (CDT): Designer](/designer/custom-data-types/custom-data-types-cdt-designer) – Creating CDTs for filtering
* [Create PDFs from Forms & Assessments](/designer/documents-and-assessments/create-pdfs-from-forms-assessments) – Using variables in PDFs
* [Automations that Trigger Outbound Communications](/designer/automations/automations-that-trigger-outbound-communications) – Using messages in automations
* [How to Create an Assessment or Form Template](/designer/documents-and-assessments/how-to-create-an-assessment-or-form-template) – Assessment data sources
# Filtering with Message Template Variables
## Overview
Message template variables in Welkin can be filtered and formatted to control how dynamic data appears in your communication templates. This is useful when you want to display a date in a specific format, truncate long text, or conditionally show values.
## What is Variable Filtering?
When you insert a variable like `{{patient.date_of_birth}}` into a message template, you can apply a filter to transform the output. Filters are appended to the variable using a pipe character (`|`).
**Syntax:**
```
{{variable_name | filter_name}}
```
## Common Filters
### Date Formatting
Format dates to display in a specific way:
```
{{patient.date_of_birth | date: "MM/DD/YYYY"}}
```
Supported formats: `MM/DD/YYYY`, `YYYY-MM-DD`, `Month DD, YYYY`
### Uppercase / Lowercase
```
{{patient.first_name | upcase}}
{{patient.last_name | downcase}}
```
### Default Value
Display a fallback when the variable is empty:
```
{{patient.phone | default: "No phone on file"}}
```
### Truncate
Limit the number of characters displayed:
```
{{patient.notes | truncate: 100}}
```
## Combining Filters
Multiple filters can be chained together:
```
{{patient.first_name | upcase | default: "Patient"}}
```
## Configuration
Variable filtering is configured directly in the message template editor in Designer. When adding a variable, use the filter syntax in the template body. Test templates using the preview functionality before publishing.
For basic variable usage, see [Filtering Message Template Variables](/designer/documents-and-assessments/filtering-message-template-variables).
# Create an Assessment or Form Template
An Assessment or Form template is a set of questions that can be used to collect information from patients or providers. The first step in creating an Assessment is to create the [Custom Data Types and Fields](/designer/documents-and-assessments/how-to-create-an-assessment-or-form-template). These will format the answer boxes used within an Assessment.
**Note:** A Custom Data Type Field can only be used once in an Assessment/Form, but can be utilized in alternative Assessment/Forms.
The steps to creating a new Assessment Template are as follows:
1. Log into Designer portal
2. Select "Create Draft" on the top right hand corner
3. Click on "Forms" in the left side blue menu under "Visual Components"
4. Click on the orange "+ New" button in the top right corner
5. Add a title for the Assessment. The title will appear as the form's name in Care
6. The "Auto complete submitted" checkbox will cause the Ass
***
## Related Topics
* [Add Assessments to a Template](/designer/documents-and-assessments/how-to-add-assessments-to-a-template) – including assessments in encounter templates
* [Configure Scored Assessments](/designer/documents-and-assessments/designer-how-to-configure-scored-assessments) – setting up scoring
* [Add Conditionality to Assessments](/designer/documents-and-assessments/how-to-add-conditionality-to-assessments) – conditional logic
* [Custom Data Types](/designer/custom-data-types/custom-data-types) – CDT fundamentals
* [Forms and Assessments](https://docs.welkinhealth.com/care/forms-and-assessments/forms-and-assessments) – completing assessments in Care
* [Associate Assessments with Programs](/designer/documents-and-assessments/how-to-associate-assessments-with-programs) – linking to programs
# Associate Assessments with Programs
## Overview
Welkin Health allows organizations to associate assessments (forms) with specific Programs and Phases. This association controls when and to whom assessments are available in the Care app based on a patient's enrollment status and care pathway.
When an assessment is associated with a Program/Phase, it will only appear as an option in the Care app if the patient is actively enrolled in that Program and Phase. This ensures assessments are presented at the appropriate time during the patient's care journey and prevents irrelevant assessments from appearing.
## Key Concepts
* **Program** – A complete care pathway (e.g., "Diabetes Management," "Behavioral Health")
* **Phase** – A stage within a program (e.g., "Initial Assessment," "Stabilization," "Maintenance")
* **Assessment Association** – Linking a form to specific Program/Phase combinations
* **Visibility Control** – The ability to show/hide assessments based on enrollment status
## Impact on Care Portal
When an assessment is associated with Program(s)/Phase(s):
* The assessment **appears in Care** only when the patient is enrolled in the associated Program AND Phase
* The assessment **does not appear** if:
* The patient is not enrolled in any associated Program
* The patient is in a different Phase of the Program
* The patient is in a different Program entirely
* The **"Start Assessment" option** is unavailable in the Assessment tab unless enrollment conditions are met
* **Encounter associations** with the assessment are also blocked unless enrollment is active
## Prerequisites
Before associating assessments with programs:
1. You have already created an Assessment/Form in Designer
2. You have created the Programs and Phases you want to associate with
3. You have appropriate permissions to edit forms and program configurations
For information on creating Programs and Phases, see [Programs and Phases](/designer/programs-and-profiles/programs-and-phases).
## Step-by-Step: Associate an Assessment with a Program
### Step 1: Access the Assessment Template
1. Log into Designer
2. Click **Create Draft** to start a new configuration draft
3. Navigate to **Visual Components** > **Forms** in the left sidebar
4. Find and click on the assessment you want to associate with a Program/Phase
### Step 2: Open Program Association Settings
1. In the form editor, look for the **Program Association** or **Program/Phase** section
2. This is typically located in the form settings area (may be a tab or collapsible section)
3. You should see a list of available Programs and Phases
### Step 3: Select Program(s) and Phase(s)
1. Review the list of available Programs
2. For each Program, select which Phase(s) the assessment should appear in:
* Check the box next to **Program Name** > **Phase Name**
* Leave unchecked if the assessment should NOT appear in that Phase
**Example Associations:**
For a "Depression Screening" assessment, you might select:
* Mental Health Program > Initial Intake Phase ✓
* Mental Health Program > Stabilization Phase ✓
* Mental Health Program > Maintenance Phase ✗ (not needed after initial assessment)
For a "Vital Signs" assessment, you might select:
* Chronic Disease Program > Initial Assessment Phase ✓
* Chronic Disease Program > Quarterly Review Phase ✓
* Hypertension Program > Monthly Check-In Phase ✓
### Step 4: Save and Publish
1. Click **Save** to save your form configuration
2. Click **Publish** to make the assessment available in Care with the Program/Phase associations active
3. The assessment is now visible only to patients enrolled in the selected Program/Phase combinations
## Advanced Configuration
### Single Assessment, Multiple Programs
You can associate one assessment with multiple Programs:
**Example: "Medication Adherence" Assessment**
* Diabetes Program > All Phases ✓
* Hypertension Program > All Phases ✓
* Behavioral Health Program > Treatment Phase ✓
Care team members see this assessment only when patients are enrolled in one of these programs.
### Optional vs. Required Assessment Association
**Note:** Some organizations may have assessments with no Program/Phase restrictions. These assessments are typically:
* General questionnaires available to all patients
* Intake screenings used across programs
* Follow-up surveys for any patient
Configure Program associations only when the assessment is **specific to a care pathway**.
## Impact on Care Team Experience
### Before Program Association
Without Program/Phase associations, the "Start Assessment" drawer shows:
* All available assessments
* Regardless of patient's enrolled program
* Care team must manually determine which is appropriate
### After Program Association
With Program/Phase associations, the "Start Assessment" drawer shows:
* Only assessments relevant to patient's current Program/Phase
* Reduces confusion about which assessments apply
* Streamlines care workflow
* Prevents incorrect assessments from being administered
## Testing Your Configuration
### Step 1: Enroll Test Patient
1. Log into the Care app
2. Navigate to a test patient's profile
3. Enroll the patient in a Program and Phase (e.g., "Diabetes > Initial Assessment")
### Step 2: Verify Assessment Visibility
1. Click on the **Assessments** tab
2. Click **Start Assessment**
3. Verify that only assessments associated with "Diabetes > Initial Assessment" appear
4. Confirm unrelated assessments do NOT appear
### Step 3: Test Phase Changes
1. Move the patient to a different Phase (e.g., from "Initial Assessment" to "Quarterly Review")
2. Open the Assessment drawer again
3. Verify the list of available assessments changes appropriately
### Step 4: Test Dis-enrollment
1. End the patient's enrollment in the Program
2. Open the Assessment drawer
3. Confirm associated assessments no longer appear
## Modifying Program Associations
If you need to update Program/Phase associations:
1. Create a new Draft in Designer based on current configuration
2. Navigate to the form
3. Update the Program/Phase checkboxes as needed
4. Save and publish
5. Changes take effect immediately in Care
## Best Practices
1. **Clear Naming** – Use descriptive assessment names so the Program/Phase association makes sense
2. **Logical Grouping** – Associate assessments to Programs where they're clinically relevant
3. **Document Decisions** – Record why specific assessments are associated with specific Programs
4. **Regular Review** – Periodically review associations to ensure they still match care workflows
5. **Test Thoroughly** – Test with multiple Program/Phase scenarios before production rollout
6. **User Training** – Ensure care team understands why assessments appear/disappear based on enrollment
7. **Consider Alternatives** – For optional assessments not tied to a specific program, leave associations empty
## Common Scenarios
### Scenario 1: Program-Specific Assessment
**Assessment:** "HbA1c Target Review" **Association:** Diabetes Program > All phases **Rationale:** Only relevant to diabetic patients
### Scenario 2: Phase-Specific Assessment
**Assessment:** "Initial Psychosocial History" **Association:** Behavioral Health Program > Initial Intake only **Rationale:** Completed once at program start
### Scenario 3: Multi-Program Assessment
**Assessment:** "Medication Side Effects Screening" **Association:**
* Hypertension Program > All phases
* Diabetes Program > All phases
* Behavioral Health Program > All phases **Rationale:** Relevant across multiple disease management programs
### Scenario 4: Universal Assessment
**Assessment:** "Patient Satisfaction Survey" **Association:** None (no Program/Phase restrictions) **Rationale:** Should be available to all patients regardless of program
## Related Topics
* [Programs and Phases](/designer/programs-and-profiles/programs-and-phases) – Designing program structures
* [How to Create an Assessment or Form Template](/designer/documents-and-assessments/how-to-create-an-assessment-or-form-template) – Creating forms
* [How to Add Conditionality to Assessments](/designer/documents-and-assessments/how-to-add-conditionality-to-assessments) – Conditional logic within forms
* [Designer: How to Configure Scored Assessments](/designer/documents-and-assessments/designer-how-to-configure-scored-assessments) – Assessment scoring
* [Encounters and Dependencies](/designer/notifications-and-communications/encounters-and-dependencies) – Linking assessments to encounters
# Add Assessments to a Template
## Overview
Welkin Health enables you to embed assessments (forms) directly into Message Templates, allowing organizations to send communications to patients that include interactive assessments they can complete. This functionality makes it easy for patients to complete health evaluations, check-ins, and surveys directly from communication channels without requiring them to log into a separate portal.
To add assessments to a Message Template, you'll use Patient Facing Assessment (PFA) Folders as the vehicle for delivery. Assessments are grouped in PFA Folders, which are then embedded as links in Message Templates.
## Key Concepts
* **Message Template** – Communication content (Email or SMS) sent to patients
* **PFA Folder** – Container holding one or more assessments with branding options
* **Assessment/Form** – The actual questionnaire or form patients complete
* **Embedded Link** – Unique URL included in message that takes patient to assessment
## Prerequisites
Before adding assessments to a Message Template, ensure:
1. **Assessment(s) Created** – Forms are already created in Visual Components > Forms
2. **PFA Folder Created** – You've grouped assessments in a PFA Folder with branding
3. **Message Template Access** – You have permissions to create/edit Message Templates
4. **Team Permissions** – Appropriate roles can send messages to patients
For guides on creating these components, see:
* [How to Create an Assessment or Form Template](/designer/documents-and-assessments/how-to-create-an-assessment-or-form-template)
* [Create Patient Facing Assessment (PFA) Folders](/designer/documents-and-assessments/create-pfa-folders)
## Step-by-Step: Add Assessments to a Message Template
### Step 1: Create or Access a Message Template
1. Log into Designer
2. Click **Create Draft** to start a new configuration 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: Compose the Message Body
Write the main message content that will be sent to patients:
1. In the message body editor, compose your communication
2. Include context about why they're being asked to complete the assessment
3. Provide any necessary instructions or background
**Example message:**
```
Hello {first_name},
As part of your ongoing care, we'd like to check in on how you're feeling.
Please take 5-10 minutes to complete the following health assessment.
Your responses help us provide you with better care.
Click the link below to get started:
[ASSESSMENT LINK WILL GO HERE]
Thank you,
Your Care Team
```
### Step 3: Insert the Assessment/PFA Link
#### Option 1: Using PFA Variable (Recommended)
1. Position your cursor in the message where the link should appear
2. Click the **Variable** button or **{}** icon (usually above message body)
3. A variables drawer opens on the right
4. Look for **PFA Links** or **Patient Facing Assessments**
5. Select the **PFA Folder** you want to embed
6. The variable is inserted into your message:
```
{{pfa_link_quarterly_assessment}}
```
The variable will automatically be replaced with the unique PFA link when the message is sent to each patient.
#### Option 2: Manual PFA Folder Selection (Alternative)
1. Below or near the message body, look for **Assessment Settings** or **Attachments**
2. Click **+ Add Assessment** or **Link Assessment**
3. From the list of available PFA Folders, select the one you want
4. The system may automatically insert a variable or provide you with a link to add
### Step 4: Add Additional Context (Optional)
After inserting the assessment link, you may want to add:
1. **Completion Instructions** – "Please complete by \[date]"
2. **What to Expect** – "You'll be asked \[number] of questions"
3. **Support Info** – "If you have questions, contact us at \[phone/email]"
4. **Reminder** – "This assessment will take approximately \[X] minutes"
**Example enhanced message:**
```
Hello {first_name},
As part of your ongoing care, we'd like to check in on how you're feeling.
Please take 5-10 minutes to complete the following health assessment.
Your responses help us provide you with better care.
Click the link below to get started:
{{pfa_link_quarterly_assessment}}
You'll be asked about your current symptoms and overall health.
Your responses are confidential and will be reviewed by your care team.
Please complete by {date_one_week_from_now}.
Questions? Contact us at (555) 123-4567.
Thank you,
Your Care Team
```
### Step 5: Configure Message Delivery Settings
1. **Delivery Method** – Choose Email or SMS
* Email: Can include longer text and formatted content
* SMS: Limited to 160 characters (multiple messages if needed)
2. **Sender** – Determine who the message comes from
* Your organization name
* A specific care team member
* A general clinic inbox
3. **Timing** (if using automation)
* Immediate send
* Scheduled for specific date/time
* Triggered by patient event
### Step 6: Preview the Message
1. Click **Preview** to see how the message appears to patients
2. Verify:
* Message text is clear and professional
* Assessment link is visible
* Formatting looks good (especially if using Email)
* Link works properly
3. For Email: Preview both desktop and mobile views
4. For SMS: Verify character count and message breaks
### Step 7: Save and Test
1. Click **Save** to save the Message Template
2. If part of automation, configure trigger and conditions
3. **Test before publishing:**
* Send test message to yourself or team member
* Click the assessment link in the actual message
* Verify assessment appears correctly
* Complete a test assessment to confirm data is captured
* Check that responses appear in patient profile
### Step 8: Publish
1. Review all settings one final time
2. Click **Publish** to make the Message Template available
3. Template is now available for:
* Manual sending by care team members
* Automated sending via automations
* Multi-use across multiple patient communications
## Using Assessments in Different Message Types
### Patient Check-in Messages
**Purpose:** Regular health status updates
**Message Template Example:**
```
Hi {patient_first_name},
It's time for your monthly check-in. Please let us know how you've been doing
by completing the assessment below.
{{pfa_link_monthly_check_in}}
Takes about 5 minutes. Thank you!
```
### Post-Visit Assessments
**Purpose:** Follow-up after appointments or encounters
**Message Template Example:**
```
Thank you for your visit on {visit_date}.
To help us provide better care, please complete this brief assessment:
{{pfa_link_post_visit_feedback}}
Your feedback is valuable and helps us improve our services.
```
### Program Enrollment Assessments
**Purpose:** Baseline assessment when enrolling in new care program
**Message Template Example:**
```
Welcome to the {program_name} program!
To get started, we need to gather some baseline information.
Please complete this assessment:
{{pfa_link_program_enrollment}}
This helps us understand your current health status and create a personalized care plan.
```
### Medication Management Assessments
**Purpose:** Monitor medication adherence and side effects
**Message Template Example:**
```
Hi {patient_first_name},
Please help us monitor how your {medication_name} is working by
completing this brief assessment:
{{pfa_link_medication_adherence}}
Your responses help us ensure the medication is helping you and not causing problems.
```
## Automating Assessment Delivery
### Using Message Templates with Automations
To automatically send Message Templates containing assessments:
1. Create an automation (see [Designer: How to Create Automations](/designer/automations/designer-how-to-create-automations))
2. Set **Trigger Event** (e.g., "Program Enrollment", "Date Milestone Reached", "Assessment Completed")
3. Set **Conditions** (e.g., "Patient in Diabetes Program")
4. Set **Action** to "Send Message"
5. Select your Message Template containing the assessment
6. Configure timing (immediate, delayed, etc.)
7. Publish the automation
**Example Automation:**
```
Trigger: Patient enrolled in Diabetes Management program
Condition: Patient age > 18
Action: Send Message Template "Diabetes Program Welcome"
Timing: Immediately upon enrollment
```
When this automation fires, patients receive the welcome message with the embedded assessment link.
## Best Practices
1. **Clear Instructions** – Explain why the assessment is important and what to expect
2. **Appropriate Timing** – Don't overwhelm patients with too many assessments
* Space assessments at least 2-4 weeks apart
* Align with care plan schedule
3. **Mobile-Friendly** – Ensure assessment link works on mobile phones
4. **Character Limits** – For SMS, keep message short; link should be prominent
5. **Branding** – Ensure PFA Folder uses your organization's logos and colors
6. **Completion Reminders** – Consider follow-up messages if patient doesn't complete
7. **Thank You Messages** – Send confirmation after completion
8. **Data Utilization** – Review assessment responses and use them to inform care decisions
9. **Privacy Assurance** – Mention data privacy/confidentiality in message if appropriate
10. **Test Thoroughly** – Always test message and assessment link with actual patients before broader rollout
## Troubleshooting
### PFA Link Not Appearing in Message
**Problem:** PFA variable shows instead of link or link is missing
**Solutions:**
* Verify PFA Folder is published in Designer
* Confirm you selected the correct PFA Folder when inserting variable
* Check that message template is published
* Refresh Designer and try inserting variable again
### Assessment Not Loading When Patient Clicks Link
**Problem:** Patient clicks link but gets error or blank page
**Solutions:**
* Verify PFA Folder is published
* Check that assessments in the folder are published
* Test link in different browser
* Clear browser cache and retry
* Verify patient has permission to access the assessment
### Link Expires Before Patient Completes
**Problem:** Patient tries to access assessment after some time and gets error
**Solutions:**
* Check PFA Folder expiration settings (should be "Never" or "30+ days" for most use cases)
* Resend link if it has expired
* Consider shortening time allowed before completion
* Set reminder automation to send before expiration
### Message Not Being Sent
**Problem:** Automation or manual send doesn't deliver message with assessment
**Solutions:**
* Verify Message Template is published
* Check patient has valid email address (for Email) or phone (for SMS)
* Verify automation trigger conditions are met
* Check system logs for delivery failures
* Confirm user has permission to send messages
## Related Topics
* [How to Create an Assessment or Form Template](/designer/documents-and-assessments/how-to-create-an-assessment-or-form-template) – Creating forms
* [Create Patient Facing Assessment (PFA) Folders](/designer/documents-and-assessments/create-pfa-folders) – Creating PFA containers
* [Designer: How to Create Automations](/designer/automations/designer-how-to-create-automations) – Automating message delivery
* [Filtering With Message Template Variables](/designer/documents-and-assessments/filtering-message-template-variables) – Advanced message personalization
* [Automations that Trigger Outbound Communications](/designer/automations/automations-that-trigger-outbound-communications) – Message automations
# Configure Scored Assessments
A scored assessment allows you to numerically represent the outcome of an assessment.
After creating the question of the assessment, select "Scoring Groups" and click on "+Group"
Enter a title for the scoring group
Then, select the Data Type Field that you want to associate a numerical value with. Only list type values are available.
The CDT selected will show the corresponding answers for which you can assign the numerical value
To add another field, select "+Field"
Continue to add fields for the CDTs of the assessment for which you want to assign a numerical value and would like to be used in the scoring of the assessment.
To add a new scoring group, select "+Group"
Adding additional scoring groups allows you to compute different scores within the same assessment.
When finished, click on "Save Changes"
When an
# Create PDFs from Forms/Assessments
## Overview
Welkin allows you to automatically generate PDF documents when care team members or patients complete assessments in the Care app. PDF templates enable you to create professional, branded documents that capture assessment responses, scores, and other relevant data in a portable format suitable for printing, sharing with patients, or storing in external medical records systems.
This guide explains how to create and configure PDF templates for your assessments using Microsoft Word documents.
## Key Benefits
* **Professional Documentation** – Generate standardized clinical documents
* **Patient Handouts** – Provide assessment results directly to patients
* **Records Management** – Create documentation for medical records
* **Care Plan References** – Attachment points for care planning meetings
* **Multi-Assessment PDFs** – Combine results from multiple assessments into a single document
## Prerequisites
1. You have already created an Assessment/Form in Designer
2. You have access to Microsoft Word to create the PDF template
3. Your CDTs (Custom Data Types) are published and used in the assessment
4. You have appropriate permissions to edit forms in Designer
## Step 1: Access the Form Template Configuration
1. Log into Designer
2. Click **Create Draft** to start a new configuration draft
3. Navigate to **Visual Components** > **Forms** in the left sidebar
4. Find and click on the form that needs a PDF template added
## Step 2: Open the Template Editor
1. In the form editor, locate the **Edit Form** section on the left side
2. Click on **Template** (or "PDF Template" depending on your version)
3. You should see:
* **System Variables** list on the right sidebar
* A template preview area
* Instructions for template formatting
## Step 3: Review Available Variables
### System Variables
System Variables are standard data fields available for use in your PDF template. The right sidebar displays a complete list. Common system variables include:
* `{{patient_name}}` – Full name of the patient
* `{{patient_dob}}` – Date of birth
* `{{patient_mrn}}` – Medical record number
* `{{completion_date}}` – When the assessment was completed
* `{{completed_by}}` – Name of care team member who submitted
* `{{assessment_date}}` – Date assessment was started
* `{{encounter_date}}` – Related encounter date if applicable
* `{{assessment_title}}` – Name of the assessment form
**Important:** Use the exact format shown for all system variables (with double curly braces: `{{ }}`)
### Custom Data Type Variables
You can also reference CDT fields from the current assessment:
* `{{cdt_fieldname}}` – Single field values
* `{{cdt_fieldname_label}}` – Display label for a field (useful for list/select options)
**Example:**
* `{{depression_score}}` – Displays the numeric score
* `{{depression_assessment_date}}` – Displays the date the assessment was completed
### Cross-Assessment Variables
You can include System Variables and CDT fields from other assessments:
* `{{assessment_name.cdt_field}}` – Reference a field from a different assessment
* Example: `{{vital_signs.systolic_pressure}}` – Display systolic pressure from the vital signs assessment
## Step 4: Create Your Word Document Template
### Setup Instructions
1. **Open Microsoft Word** on your computer
2. **Create a new document** with your organization's branding:
* Logo (top of document)
* Organization name and contact information
* Assessment title section
3. **Insert Variables** where you want data to appear:
* Type or copy the variable syntax exactly as shown: `{{variable_name}}`
* Variables will be replaced with actual data when the PDF is generated
4. **Organize Content** logically:
* Header with patient information
* Assessment title and date
* Questions and answers
* Scores or results
* Footer with clinic information
### Template Example Structure
```
[Your Clinic Logo]
DEPRESSION SCREENING ASSESSMENT
Patient Name: {{patient_name}}
Date of Birth: {{patient_dob}}
Medical Record #: {{patient_mrn}}
Assessment Completed: {{completion_date}}
Completed by: {{completed_by}}
---
Question 1: Have you felt sad or depressed?
Patient Response: {{depression_q1_response}}
Question 2: Loss of interest in activities?
Patient Response: {{depression_q2_response}}
---
Depression Screening Score: {{depression_score}}/27
Result Interpretation: {{depression_score_interpretation}}
---
[Your Clinic Footer Information]
```
### Formatting Best Practices
1. **Use Clear Headings** – Organize sections with headers and subheaders
2. **Include Instructions** – Add explanatory text for care team or patient
3. **Add Interpretation Guides** – Include what scores mean (e.g., "0-5: Minimal, 6-10: Mild...")
4. **Professional Appearance** – Use consistent fonts, colors, and spacing
5. **White Space** – Leave adequate space for readability
6. **Page Breaks** – Control where section breaks occur for multi-page documents
### Special Formatting Options
You may be able to use:
* **Conditional sections** – Show some content only if certain fields have values
* **Tables** – Organize question/answer pairs in table format
* **Bullet lists** – For multiple response options
* **Bold/Italic** – For emphasis on important information
* **Page numbers** – Auto-inserted header/footer elements
## Step 5: Upload the Template
1. **Save your Word document** (use .docx format)
2. In Designer's Template section, locate the **Upload Template** button or file input
3. Click **Choose File** or **Upload**
4. Select your Word document from your computer
5. The file is processed and integrated with your form
### Verification
Once uploaded:
* The template is associated with the assessment
* The system validates that variables can be populated
* Any errors in variable syntax will be reported
* Click **Preview** (if available) to see a sample with test data
## Step 6: Test the PDF Generation
1. **Publish your configuration** in Designer
2. Go to the Care app
3. Navigate to the assessment for a test patient
4. Complete the assessment with sample data
5. Upon completion, look for a **Download PDF** option or confirmation message
6. Download and open the generated PDF to verify:
* All variables populated correctly
* Formatting appears as expected
* Content is complete and accurate
* Patient/provider information is correct
## Step 7: Adjust and Republish
If the PDF needs adjustments:
1. Go back to Designer
2. Create a new draft (based on current configuration)
3. Update the template by uploading a revised Word document
4. Re-test in Care
5. Publish when satisfied
## Multiple Assessment PDFs
### Combining Results from Multiple Assessments
Some PDFs may reference data from multiple assessments:
1. In your Word template, reference fields from multiple CDTs
2. Example: Show depression score AND vital signs on same document
3. Use the cross-assessment variable syntax: `{{assessment_name.field}}`
4. Organize logically with headers for each assessment section
## Troubleshooting
### Variables Not Populating
**Problem:** PDF shows `{{variable_name}}` instead of actual data
**Solutions:**
* Verify variable syntax is exactly correct (check spelling, spacing, braces)
* Confirm the CDT field exists and is published
* Check that data was actually entered for that field in the assessment
* Re-upload the template
### PDF Generation Fails
**Problem:** PDF doesn't generate when completing assessment
**Solutions:**
* Verify template was successfully uploaded
* Check browser console for error messages
* Try generating PDF for a different assessment to isolate the issue
* Contact support if problem persists
### Formatting Issues
**Problem:** PDF layout doesn't match the Word document
**Solutions:**
* Verify Word document uses standard fonts (Arial, Times New Roman, etc.)
* Check that graphics/images are embedded, not linked
* Simplify complex formatting (tables within tables, etc.)
* Test with a simpler template first
## Best Practices
1. **Test Thoroughly** – Use multiple test patients with various data entry patterns
2. **Keep Templates Simple** – Complex Word documents may not convert cleanly
3. **Regular Updates** – Review and update templates as assessment questions change
4. **Version Control** – Document which template version corresponds to which assessment version
5. **Patient-Friendly** – If distributing to patients, ensure language is clear and supportive
6. **Include Context** – Add interpretation guides so results are understood
7. **Brand Consistency** – Use organization logos and colors for professional appearance
## Related Topics
* [How to Create an Assessment or Form Template](/designer/documents-and-assessments/how-to-create-an-assessment-or-form-template) – Creating forms
* [How to Associate Assessments with Programs](/designer/documents-and-assessments/how-to-associate-assessments-with-programs) – Linking forms to care programs
* [Filtering With Message Template Variables](/designer/documents-and-assessments/filtering-message-template-variables) – Using variables in messages
* [Create Patient Facing Assessment (PFA) Folders](/designer/documents-and-assessments/create-pfa-folders) – Sending assessments to patients
* [Designer: How to Configure Scored Assessments](/designer/documents-and-assessments/designer-how-to-configure-scored-assessments) – Assessment scoring
# Create PFA Folders
## Overview
Patient Facing Assessments (PFAs) are assessment forms that can be sent directly to patients or contactable profiles via a unique, shareable URL. PFAs are delivered through Email or SMS and allow patients to complete assessments independently, without requiring Care app access. Multiple assessments can be grouped within a single PFA Folder and delivered via one link, and PFAs can be customized with your organization's branding, colors, and logos.
## Key Features
* **Self-Service Assessment Completion** – Patients complete forms on their own schedule
* **Multiple Assessments per Link** – One PFA Folder can contain multiple related assessments
* **Unique URLs** – Each PFA link is unique and tracked for completion status
* **Email & SMS Delivery** – Send via either communication method
* **White-labeling** – Customize appearance with organization branding
* **Single Active Link** – Only one PFA link is active per patient at a time
* **Progress Tracking** – Monitor completion status in Care portal
## Prerequisites
Before creating a PFA Folder:
1. You have already created Assessment/Form template(s) in Designer
2. You have appropriate permissions to edit visual components in Designer
3. You understand your organization's branding guidelines
For information on creating assessment forms, see [How to Create an Assessment or Form Template](/designer/documents-and-assessments/how-to-create-an-assessment-or-form-template).
## Step-by-Step: Create a PFA Folder
### Step 1: Access PFA Configuration in Designer
1. Log into Designer
2. Click **Create Draft** to start a new configuration draft
3. Navigate to **Visual Components** > **PFA Folder** in the left sidebar
4. Click **+ New** in the upper right corner to create a new PFA Folder
### Step 2: Enter Basic Information
Fill in the following fields:
1. **Title** – Display name for the PFA Folder (visible to patients)
* Example: "Quarterly Health Assessment"
* Should be clear and professional
2. **Name** – Internal system name (lowercase, numbers, underscores, hyphens)
* Auto-populates from Title but can be customized
* Example: `quarterly-health-assessment`
* This name appears in system logs and dropdowns
3. **Description** (optional) – Internal notes about the PFA's purpose
* Helps care team understand when/why to use this PFA
* Not visible to patients
### Step 3: Add Assessments to the Folder
1. Click **+ Add Assessment** or similar button
2. From the list of available assessments, select which forms to include:
* Can add one or multiple assessments
* Assessments appear in the order you add them
* Patients complete them sequentially
**Example PFA with Multiple Assessments:**
* Vital Signs Assessment (first)
* Depression Screening (second)
* Medication Adherence Survey (third)
### Step 4: Configure Branding (Optional)
Customize the appearance for your organization:
1. **Organization Logo** – Upload your organization's logo
* Appears at the top of the patient-facing form
* Recommend: PNG or JPG, 200-300px width
2. **Color Scheme** – Select primary and accent colors
* Primary color: Used for buttons and headings
* Accent color: Used for highlights
* Choose colors that match your brand guidelines
3. **Organization Name** – Display name shown to patients
4. **Contact Information** – Optional footer with clinic details
* Phone number
* Email
* Address
5. **Help Text** – Optional instructions shown at the top
* Brief explanation of what the patient is completing
* Example: "Please take 5-10 minutes to complete this health check-in"
### Step 5: Configure Completion Behavior
1. **Allow Discard** – Check if patients can exit/discard the PFA without completing
* If unchecked, patients must complete or explicitly cancel
2. **Completion Message** – Message shown after submission
* Example: "Thank you for completing this assessment. Your care team will review your responses."
* Default message is provided if not customized
3. **Redirect URL** (optional) – Where patient is sent after completion
* Can point to your organization's website
* Can link to patient education materials
### Step 6: Set Expiration (Optional)
1. **Link Expiration** – Set how long PFA remains valid
* Options: Never expire, 7 days, 14 days, 30 days, custom
* After expiration, patients cannot access the link
* Default: No expiration (link remains active until completed)
### Step 7: Save and Publish
1. Click **Save** to save the PFA Folder configuration
2. Click **Publish** to make it available for use in Care
3. The PFA Folder is now ready to be sent to patients
## Sending PFAs to Patients in Care
Once published, PFA Folders can be sent through automations or manually by care team members.
### Manual Send (from Patient Profile)
1. Navigate to patient's profile in Care app
2. Look for **Send Assessment** or **Assessments** section
3. Select the PFA Folder you want to send
4. Choose delivery method: **Email** or **SMS**
5. Confirm patient's contact information is correct
6. Click **Send**
7. Patient receives unique link in Email or SMS
### Automated Send (via Automation)
Configure an automation to automatically send a PFA Folder:
1. Create an automation with appropriate trigger (e.g., program enrollment, date milestone)
2. Select **Send PFA Folder** as the action
3. Choose which PFA Folder to send
4. Select delivery method (Email or SMS)
5. Publish the automation
6. Patients in matching conditions receive the PFA automatically
For more information, see [Automations that Trigger Outbound Communications](/designer/automations/automations-that-trigger-outbound-communications).
## Important Notes on PFA Behavior
### Single Active Link Per Patient
* Patient can only have **one active PFA link** at a time
* If you send a new PFA link while a previous one is active:
* The new link becomes active
* The old link is deactivated
* Only the most recent link works
* Patient must complete or discard the PFA before another can be sent
### Link Behavior
* Links are **unique per patient** – each patient gets their own URL
* Links are **not reusable** – they don't expire or need expiration dates once completed
* Patients **do not need to log in** to Welkin to complete a PFA
* Patients can complete PFAs on **mobile or desktop**
### Completion Tracking
* Completion status appears in Care portal
* Care team can see:
* When link was sent
* When patient completed/discarded
* Responses submitted
* Completion triggers automations (if configured)
## Best Practices
1. **Grouping Strategy** – Include 3-5 related assessments per PFA Folder for patient convenience
* Too many assessments = patient fatigue
* Too few assessments = many separate emails
2. **Clear Naming** – Use patient-friendly titles that explain why assessment is needed
* ✓ Good: "Monthly Check-in"
* ✗ Poor: "CDTF\_Assessment\_Bundle\_v3"
3. **Branding Consistency** – Ensure logos and colors match patient materials and communications
4. **Timing** – Don't oversend PFAs
* Space PFAs at least 2-4 weeks apart
* Align with care plan schedule
5. **Instructions** – Include clear completion instructions in help text
* Estimate time needed to complete
* Explain why you're asking
* Note any medical context
6. **Mobile Friendly** – Test on mobile phones to ensure responsive design
7. **Contact Info** – Include support contact in case patients have questions
8. **Reminders** – Consider automating reminder sends if patients don't complete within specified timeframe
## Troubleshooting
### PFA Link Not Working
**Problem:** Patient clicks link and gets error
**Solutions:**
* Verify PFA Folder is published
* Check link wasn't already completed (single-use)
* Confirm patient's email is correct if sent via Email
* Check link expiration settings if configured
### Patient Feedback on Branding
**Problem:** Patients confused about which organization sent PFA
**Solutions:**
* Ensure organization logo is visible at top
* Add clear organization name in header
* Include contact information for support
* Use branded colors throughout
### Assessments Not Showing
**Problem:** Patient opens PFA but sees no assessments to complete
**Solutions:**
* Verify assessments are included in the PFA Folder
* Confirm assessments are published in Designer
* Check PFA Folder is published
* Resend the link if it was created before assessments were published
## Related Topics
* [How to Create an Assessment or Form Template](/designer/documents-and-assessments/how-to-create-an-assessment-or-form-template) – Creating assessment forms
* [Automations that Trigger Outbound Communications](/designer/automations/automations-that-trigger-outbound-communications) – Automating PFA sends
* [How to Add Assessments to a Template](/designer/documents-and-assessments/how-to-add-assessments-to-a-template) – Adding assessments to messages
* [Create PDFs from Forms & Assessments](/designer/documents-and-assessments/create-pdfs-from-forms-assessments) – Assessment result documentation
* [Designer: How to Create Automations](/designer/automations/designer-how-to-create-automations) – Automation basics
# Forms Conditional Logic
Welkin's Form Designer supports conditional logic to show and hide fields on forms. To use this functionality, the sections, questions and answer fields must be added to the form first. Once all of the questions and answer fields have been added, go to the "Conditions" tab within the form configuration to add your show/hide logic.
In the following scenario, I want to show a question "Enter LMP" or "Enter EDD" based on which date type will be used to calculate the gestational age.
Condition logic needed:
If date type = LMP then show "Enter LMP" question
If date type = EDD then show "Enter EDD" question
**Steps to configure the conditions for the scenario above:**
1. Go to the "Conditions" tab in the form configuration.
2. Click "Add Element".
3. Choose the section of the form where the fields you want to show/hide are located
4. Choose the field you want
# eSignature Configuration (Native)
Welkin includes a built-in eSignature capability — no third-party integration required. It supports two use cases:
* **Provider signatures** — care team members or supervisors sign off on clinical notes or assessments
* **Patient consent signatures** — patients sign consent forms as part of an assessment
Both are configured in **Designer → Forms**.
> For sending documents to patients via **DocuSign**, see [Configure eSignature (DocuSign)](https://docs.welkinhealth.com/integrations/docusign/how-to-configure-esignature).
***
## Setting up Provider eSignature
1. Click **Create Draft** on the Change Summary page of Designer
2. Select whether the draft will be **From Current Version** or **From File**, then click Submit
3. Go to **Forms** in the left side menu and open the form a provider needs to sign
4. Click the **Signature** tab within the form
5. Select either **Care Team Member and Supervisor Signature** or **Care Team Member Signature** from the Document Type dropdown
6. Add the **Supervisor Signature** and/or **Care Team Member Signature** to the variables
7. On the Template tab, add the appropriate variables from **User Signature Variables** to the assessment template document
8. Upload the template and save changes
***
## Setting up Patient Consent eSignature
1. Click **Create Draft** on the Change Summary page of Designer
2. Select whether the draft will be **From Current Version** or **From File**, then click Submit
3. Go to **Forms** in the left side menu and open the form the patient needs to sign
4. Click the **+ Consent** button in the Content section of the form
5. Add a **Label** — this is the text that appears next to the signature field (e.g. "Signature:" or "Please sign here:")
6. Click the **{x}** variable button under the Label section and copy the **Patient Signature Variable**
7. Add the variable to the Assessment PDF template
8. Upload the template
9. Check the **Required** box if the signature must be completed before the form can be submitted
10. Save changes
***
More Questions? Contact or your Implementation/CSM directly.
# How to Configure Charts and Graphs
## Overview
Charts and Graphs allow you to visualize patient data trends over time in the Care app. By configuring charts, you enable care team members and patients to see how key metrics are progressing (or regressing) and make data-informed clinical decisions. Charts pull data from Custom Data Types with numeric fields (Integer or Float) or from assessments with scoring conditions.
Supported visualization types include line graphs, bar graphs, and pie charts, each suited to different data patterns and clinical needs.
## Key Concepts
* **Data Source** – The CDT or assessment providing the numeric data
* **Data Point** – A single measurement/entry at a specific point in time
* **Time Range** – How far back to look for data (e.g., "Last 90 days")
* **Chart Type** – Visualization method (line, bar, pie)
* **Metric** – The specific field being visualized
* **Scoring** – Numeric values assigned to assessment answers
## Prerequisites
1. You have created Custom Data Types with Integer or Float fields, OR
2. You have created assessments with Scoring conditions
3. You have appropriate permissions to create visual components in Designer
4. You understand your data structure
For information on creating CDTs, see [Custom Data Types (CDT): Designer](/designer/custom-data-types/custom-data-types-cdt-designer). For scoring, see [Designer: How to Configure Scored Assessments](/designer/documents-and-assessments/designer-how-to-configure-scored-assessments).
## Step-by-Step: Create a Chart or Graph
### Step 1: Access Charts & Graphs Configuration
1. Log into Designer
2. Click **Create Draft** to start a new configuration draft
3. Navigate to **Visual Components** > **Charts and Graphs** in the left sidebar
4. Click **+ New** in the upper right corner
### Step 2: Enter Basic Chart Information
#### Title
* Display name shown in Care app
* Should be clear and descriptive
* **Examples:**
* "Blood Pressure Trend"
* "Weekly Weight Tracking"
* "Depression Screening Scores"
* "Exercise Minutes per Week"
#### Name
* Internal system name (lowercase, numbers, underscores, hyphens)
* Auto-populates from Title
* **Examples:** `blood-pressure-trend`, `weekly-weight`
### Step 3: Configure the Data Source
#### Define Default Time Range
1. **Select "# of Days"** – How many days of historical data to display by default
* Options typically: 7, 14, 30, 60, 90, 180, 365 days, or custom
* This becomes the default view; users can adjust in Care
* **Recommendation:** Choose range showing meaningful trends (90 days for most metrics)
#### Select the Data Source
1. **Choose CDT or Assessment** – Select where data comes from
* Option A: **Custom Data Type** – Use a numeric field from a CDT
* Option B: **Scored Assessment** – Use scoring from an assessment
**For CDT Data Source**
1. Select the **CDT** containing your data
2. Select the **Field** to visualize (must be Integer or Float type)
3. The chart will display all recorded values for this field over time
**Example:**
* CDT: `vital-signs`
* Field: `systolic-pressure` (Integer)
* Shows all blood pressure readings over time
**For Scored Assessment Data Source**
1. Select the **Assessment/Form**
2. Select the **Scored Field** (must have scoring configured)
3. The chart displays the score each time the assessment is completed
**Example:**
* Assessment: `Depression Screening (PHQ-9)`
* Scored Field: `total-depression-score`
* Shows PHQ-9 score each time patient completes the assessment
### Step 4: Choose Chart Type
Select the visualization type most appropriate for your data:
#### Line Graph
**Best for:** Tracking trends over time (most common)
**Use cases:**
* Weight progression
* Blood pressure readings
* Medication adherence percentages
* Test scores over time
* Progress on goals
**Features:**
* Shows continuous progression
* Easy to see trends and patterns
* Connects data points with lines
* Can display multiple metrics on same chart
**Configuration:**
* X-axis: Time (dates)
* Y-axis: Numeric values
* Optional: Add target line showing goal or normal range
#### Bar Graph
**Best for:** Comparing values across categories or time periods
**Use cases:**
* Monthly exercise minutes
* Weekly medication adherence counts
* Exercise sessions completed per week
* Comparison between two time periods
* Categorical comparisons
**Features:**
* Shows distinct values for each period
* Good for comparing quantities
* Can stack bars for multiple metrics
**Configuration:**
* X-axis: Time periods or categories
* Y-axis: Numeric values
* Optional: Stack multiple metrics
#### Pie Chart
**Best for:** Showing composition or proportions
**Use cases:**
* Assessment question responses (% answering each option)
* Distribution of medication adherence (% full/partial/none)
* Service utilization breakdown
* Risk factor prevalence
* Symptom prevalence in population
**Features:**
* Shows proportions as slices
* Easy to see relative sizes
* Typically shows one metric only
**Configuration:**
* Data source: Assessment responses or categorical counts
* Shows percentage each option represents
### Step 5: Configure Display Options
Depending on chart type, configure:
#### Labels and Titles
1. **Y-axis Label** – What the numbers represent (e.g., "mmHg", "Score", "Pounds")
2. **Chart Legend** – Show/hide metric names
3. **Data Point Labels** – Show/hide values at each data point
#### Scaling and Ranges
1. **Y-axis Scale** – Auto-calculated or manual
* Auto: System determines min/max based on data
* Manual: You set minimum and maximum values
* Useful if you want to show goal range or normal limits
2. **Goal Line/Target Range** (optional)
* Display a reference line showing target value or goal
* **Example:** Blood pressure chart with line at 140 systolic showing hypertension threshold
* **Example:** Weight chart with line showing goal weight
#### Colors and Styling
1. **Metric Color** – Choose color for line/bar/pie slice
2. **Goal Line Color** – Color for reference/target line
3. **Background** – Light or dark theme
### Step 6: Configure Multiple Metrics (Optional)
Some charts can display multiple metrics together:
#### Adding a Second Metric
1. Click **+ Add Metric** or **+ Add Series**
2. Select another CDT field or scored field
3. Choose a different color
4. The chart now displays both metrics overlaid
**Example: Dual-Metric Blood Pressure Chart**
```
Metric 1: Systolic pressure (blue line)
Metric 2: Diastolic pressure (red line)
```
Both display on same chart for easy comparison.
**Important:** Ensure metrics have compatible scales
* Example: Don't mix weight (100-200 lbs) with heart rate (60-100 bpm) without scaling adjustments
* Consider creating separate charts if scales are very different
### Step 7: Review and Save
1. Preview the chart configuration (if preview available)
2. Verify:
* Title is clear
* Data source is correct
* Chart type matches your data
* Time range is appropriate
3. Click **Save** to save in draft
### Step 8: Test and Publish
1. In Care app, navigate to a test patient with data
2. Find the new chart in their profile
3. Verify:
* Data displays correctly
* Trends are visible
* Chart is readable
* Colors are appropriate
4. Return to Designer
5. Click **Publish** to make chart available to all users
## Common Chart Configurations
### Configuration 1: Simple Weight Tracking
```
Title: Weight Trend
Chart Type: Line Graph
Data Source: CDT "biometric-measurements" → field "weight"
Days: 180 (6 months)
Y-axis Label: Pounds (lbs)
Goal Line: 180 lbs (set by care team)
Display: Show current weight label
```
**Result:** Care team sees patient's weight progression over 6 months with visual goal marker.
### Configuration 2: Dual Vital Signs
```
Title: Blood Pressure Trend
Chart Type: Line Graph
Data Source: CDT "vital-signs"
Metric 1: systolic_pressure (blue)
Metric 2: diastolic_pressure (red)
Days: 90
Y-axis Label: mmHg
Goal Lines:
- 130 (systolic threshold)
- 80 (diastolic threshold)
```
**Result:** Clear view of both BP components with threshold references.
### Configuration 3: Assessment Score Over Time
```
Title: Depression Screening Scores
Chart Type: Line Graph
Data Source: Assessment "PHQ-9 Depression Screening" → score field
Days: 365 (1 year)
Y-axis Label: PHQ-9 Score (0-27)
Y-axis Range: 0-27
Goal Line: 10 (moderate threshold)
```
**Result:** Tracks clinical response to depression treatment; care team can assess if treatment is working.
### Configuration 4: Medication Adherence
```
Title: Weekly Medication Adherence
Chart Type: Bar Graph
Data Source: CDT "medication-adherence-tracking" → field "doses_taken_this_week"
Days: 90
Y-axis Label: Doses Taken
Y-axis Range: 0-7
```
**Result:** Weekly bar chart showing adherence compliance; gaps are immediately visible.
### Configuration 5: Assessment Response Distribution
```
Title: Patient Satisfaction Responses
Chart Type: Pie Chart
Data Source: Assessment "Satisfaction Survey" → responses to question "Overall, how satisfied are you?"
```
**Result:** Shows % of patients responding Very Satisfied / Satisfied / Neutral / Dissatisfied.
## Best Practices
1. **Clear Titles** – Names should tell care team what they're looking at at a glance
2. **Appropriate Chart Types** – Match visualization to data type:
* Trends over time → Line graph
* Comparative amounts → Bar graph
* Proportions/composition → Pie chart
3. **Meaningful Time Ranges** – Choose ranges showing enough data to identify trends
* Too short (7 days) = noise, no pattern
* Too long (2+ years) = patterns buried, hard to read
4. **Include Context** – Use goal lines, thresholds, or normal ranges to give data meaning
5. **Consistent Metrics** – On multi-metric charts, ensure metrics are compatible scales
6. **Patient-Friendly** – Use labels patients understand
* "Weight (pounds)" instead of "kg"
* "Depression Severity" instead of "PHQ-9 Score"
7. **Regular Data Entry** – Charts only useful if data is entered consistently
8. **Performance** – Charts with thousands of data points may load slowly
* Consider limiting time range
* Summarize data in some cases
9. **Testing** – Always test with real patient data before publishing
10. **Documentation** – Keep notes on why each chart was created and what it's meant to show
## Troubleshooting
### Chart Not Displaying Data
**Problem:** Chart appears but no data shows
**Solutions:**
* Verify selected CDT/field has data entered for the patient
* Check date range – ensure data falls within the range
* Confirm field type is Integer or Float (required for charts)
* Verify chart is published
* Check patient enrollment status (if chart uses assessment from restricted program)
### Chart Shows Incorrect Data
**Problem:** Chart displays wrong values or metrics
**Solutions:**
* Verify correct CDT/field is selected as data source
* Check field isn't being calculated incorrectly
* Review any formulas or scoring conditions
* Confirm field name hasn't been changed (would break chart reference)
### Chart is Hard to Read
**Problem:** Chart cluttered, overlapping, or difficult to interpret
**Solutions:**
* Reduce time range to show less data
* Remove non-essential metrics
* Change chart type (line to bar, etc.)
* Increase Y-axis range if data compressed
* Use different colors for clarity
* Add goal lines/thresholds for context
### Performance Issues
**Problem:** Chart is slow to load or unresponsive
**Solutions:**
* Reduce time range (e.g., 30 days instead of 365)
* Reduce number of metrics displayed
* Consider creating separate charts for different metrics
* Check if there are thousands of data points (consider data summarization)
## Related Topics
* [Charts & Graphs: Filter, Change Date, and by Data Point](/designer/charts-and-graphs/charts-graphs-filter-change-date-and-by-data-point) – Using charts in Care
* [Custom Data Types (CDT): Designer](/designer/custom-data-types/custom-data-types-cdt-designer) – Creating numeric fields for charts
* [Designer: How to Configure Scored Assessments](/designer/documents-and-assessments/designer-how-to-configure-scored-assessments) – Assessment scoring
* [Patient Data View](/designer/programs-and-profiles/patient-data-view) – How charts appear in Care
* [Create Formulaic Custom Data Type Fields](/designer/custom-data-types/create-formulaic-custom-data-type-fields) – Calculated fields for charts
# Filter, Change Date, and Data Points
## Overview
Once you have built and published your Charts and Graphs in Designer, they become available in the Care app for care team members and patients to view. As clinical data is entered over time, charts display trends and patterns in patient metrics, allowing providers to make informed care decisions.
This guide explains how to use Charts and Graphs to visualize and filter patient data views over a stretch of time, and how to filter single or multiple data points to focus on specific information.
## Prerequisites
* You have already created and published a Chart or Graph in Designer
* Your CDTs (Custom Data Types) are configured with Integer or Float field types to be visualized
* Patient data has been entered for the fields you're monitoring
For an overview of Charts and Graphs, see [Charts & Graphs: How to Configure](/designer/charts-and-graphs/charts-graphs-how-to-configure).
## Viewing Charts in the Care App
### Accessing Charts
1. Log into the Care app
2. Navigate to a patient's profile
3. Click on the **Charts & Graphs** section (or **Data Views** depending on your configuration)
4. Select the specific chart or graph you wish to view
5. The chart displays with:
* **X-axis:** Time periods (days, weeks, months depending on configuration)
* **Y-axis:** Metric values (numeric data from your CDT fields)
* **Data points:** Individual measurements entered over time
## Filtering by Date Range
### Default View
The chart initially displays data based on the default date range set during chart configuration in Designer (e.g., "Last 90 days"). The date range is typically shown at the top of the chart.
### Changing the Date Range
To adjust the date range and view different time periods:
1. Look for the **Date Range selector** at the top of the chart
2. Click to open the date range options
3. Common options include:
* **Last 7 Days** – Past week of data
* **Last 30 Days** – Past month of data
* **Last 90 Days** – Past three months of data
* **Last 6 Months** – Past six months of data
* **All Time** – All available data points
* **Custom Date Range** – Specify start and end dates manually
4. Select your desired date range
5. The chart updates automatically to display only data within the selected period
### Custom Date Selection
To set a specific custom date range:
1. Click **Custom Date Range** (or **Custom** option)
2. Select a **Start Date** from the date picker
3. Select an **End Date** from the date picker
4. Click **Apply** or **Update**
5. The chart refreshes to show only data between those dates
## Filtering by Data Points
### Understanding Data Points
A "data point" represents a single measurement or entry. For example:
* A single blood pressure reading
* One depression screening score
* A patient's weight measurement on a specific date
Charts may track multiple data points from the same CDT field, showing how values change over time.
### Single Data Point Selection
To focus on a specific data point or narrow the data:
1. Locate the **Data Point Filter** section (usually near the date range selector)
2. If multiple metrics are being displayed, you can often toggle individual ones on or off
3. Click on the specific data point or metric name to highlight or isolate it
4. The chart updates to show only the selected data point over time
### Multiple Data Point Filtering
To view and compare multiple specific data points:
1. Click the **Data Point Filter** or **Metrics** selector
2. Check the boxes next to each data point you want to display
3. Uncheck any data points you want to hide
4. The chart updates to show only selected data points, allowing for side-by-side comparison
**Example use cases:**
* **Vital Signs:** View systolic AND diastolic pressure together
* **Assessment Scores:** Compare depression screening score against medication adherence score
* **Dual Metrics:** Track weight alongside BMI
## Building Your Data Entry Pattern
### Initial Setup
When first creating charts for a patient, you'll need to enter at least one data point:
1. In the Care app, navigate to the appropriate assessment or data entry form
2. Complete the form with the metric data (e.g., enter blood pressure, weight, screening score)
3. Save and submit the assessment
4. The data point is recorded with the completion date/time
### Growing Your Data Set
As you enter more data points over time:
* **Week 1:** First measurement recorded
* **Week 2:** Second measurement shows a trend starting to form
* **Week 3:** Third measurement allows pattern recognition
* **Week 4+:** Sufficient data points to see meaningful trends
The chart grows with each new data point entered, making patterns and trends increasingly visible.
## Practical Examples
### Example 1: Blood Pressure Monitoring
1. Patient enrolled in Hypertension program
2. BP readings recorded weekly (systolic/diastolic)
3. Open BP chart in Care app
4. Default view shows last 90 days
5. Filter to see **only systolic pressure** over the past month
6. Identify if readings are trending downward (positive response to treatment)
### Example 2: Depression Screening Tracking
1. Patient completes depression screening assessment
2. Initial score: 18 (moderate depression)
3. After 4 weeks: Score 12 (improvement)
4. After 8 weeks: Score 8 (good improvement)
5. View chart with custom date range from enrollment to present
6. Filter to show depression score alongside treatment adherence
7. Care team reviews correlation between adherence and score improvement
### Example 3: Multi-Metric Comparison
1. Chart configured to display weight, BMI, and exercise frequency
2. View all three metrics together over 6 months
3. Filter to show **only weight and BMI** to focus on obesity metrics
4. Uncheck exercise frequency for cleaner visualization
5. Identify whether weight loss correlates with BMI improvement
## Troubleshooting
### No Data Points Appearing
**Cause:** No data has been entered for the selected time period or metric
**Solution:**
* Verify data has been entered in the Care app for this patient
* Check that the date range includes when data was entered
* Confirm the CDT field is correctly configured and published
### Chart Not Updating
**Cause:** Chart may be cached or not refreshing
**Solution:**
* Refresh your browser (Ctrl+R or Cmd+R)
* Clear browser cache if problem persists
* Log out and log back into Care
### Missing Metrics in Filter
**Cause:** Not all expected fields are appearing in the filter options
**Solution:**
* Verify the field type is Integer or Float in the CDT definition
* Confirm the chart includes the field in its data source configuration
* Republish the chart in Designer if recently modified
## Best Practices
1. **Consistent Data Entry** – Enter data at regular intervals (weekly, monthly) for cleaner trends
2. **Use Appropriate Date Ranges** – Select ranges that show enough data to identify patterns without overwhelming detail
3. **Compare Relevant Metrics** – Filter to show data points that have clinical significance together
4. **Document Observations** – Add notes to patient charts when filtering data reveals concerning trends
5. **Review Regularly** – Check charts during care planning meetings to inform treatment adjustments
## Related Topics
* [Charts & Graphs: How to Configure](/designer/charts-and-graphs/charts-graphs-how-to-configure) – Designing charts in Designer
* [Create Formulaic Custom Data Type Fields](/designer/custom-data-types/create-formulaic-custom-data-type-fields) – Calculated fields for charts
* [Custom Data Types (CDT): Designer](/designer/custom-data-types/custom-data-types-cdt-designer) – Field configuration
* [Patient Data View](/designer/programs-and-profiles/patient-data-view) – Overview of data visualization in Care
* [Designer: How to Configure Scored Assessments](/designer/documents-and-assessments/designer-how-to-configure-scored-assessments) – Assessment scoring for charts
# Configuring Security Policies
## Overview
Security Policies in Welkin implement **Attribute-Based Access Control (ABAC)**, allowing administrators and implementers to define fine-grained rules that control what data users can access. Policies are configured in the Designer and applied to user roles.
For setup steps, see [Setup Security Policies](/designer/security/setup-security-policies). For detailed policy rule reference, see [Security Policy Detail](/designer/security/security-policy-detail).
***
## What Security Policies Control
Security policies define access at the data level – not just which pages a user can see, but which specific records, fields, and actions they can perform. For example:
* A care manager can only see patients assigned to their care team
* A supervisor can view all patients in their region
* An admin can view all patients across all regions
***
## Key Concepts
**Attributes** – properties used to evaluate access rules, such as:
* Patient region or territory
* Care team membership
* Program enrollment
* User role
**Rules** – conditions that must be true for access to be granted. Rules can combine multiple attributes using AND/OR logic.
**Scope** – whether the policy applies to individual records, all records of a type, or a filtered subset.
***
## Applying Policies to Roles
Once a policy is created in the Designer:
1. Navigate to **Roles** in the Admin Portal or Designer.
2. Edit the relevant role.
3. Under **Security Policies**, attach the appropriate policy.
4. Publish the change.
Users assigned to that role will have their data access governed by the attached policy.
***
## Publishing
Security policy changes require a draft and publish cycle in the Designer before they take effect in the Care Portal.
***
## Related Topics
* [Setup Security Policies](/designer/security/setup-security-policies) – step-by-step configuration guide
* [Security Policy Detail](/designer/security/security-policy-detail) – detailed policy rule reference
* [Security Policies: Attribute Based Access Control](https://docs.welkinhealth.com/admin/security/security-policies) – ABAC overview in Admin
* [Defining Regions and Territories](/designer/security/defining-regions-and-territories) – region/territory attributes
* [Roles](https://docs.welkinhealth.com/care/getting-started/roles) – user roles in Care
# Setup Security Policies
## Overview
Security Policies implement Attribute-Based Access Control (ABAC) in Welkin. They define rules that determine which patient records, data types, and actions are accessible to users based on their attributes (role, region, care team assignment, etc.). This page covers the initial setup process.
For detailed policy rule configuration, see [Security Policy Detail](/designer/security/security-policy-detail). For an overview of how policies work, see [Configuring Security Policies](/designer/security/configuring-security-policies).
***
## Before You Begin
Before creating security policies:
1. Define your user roles in the Admin Portal
2. Define regions and territories if your organization uses geographic access control (see [Defining Regions and Territories](/designer/security/defining-regions-and-territories))
3. Understand your organization's data access requirements – which users should see which patients
***
## Creating a Security Policy
1. In the Designer, navigate to **Security Policies**.
2. Click **+ Add Policy**.
3. Enter a **Name** for the policy (e.g., "Care Manager – Own Patients Only").
4. Define the **access rules**:
* Select the **entity** the policy applies to (Patient, CDT, Program, etc.)
* Set the **conditions** that must be true for access to be granted
* Set the **permitted actions** (View, Edit, Delete)
5. Save the policy.
***
## Attaching Policies to Roles
1. Go to **Roles** in the Designer or Admin Portal.
2. Edit the target role.
3. Under **Security Policies**, attach the appropriate policy.
4. Save and publish.
***
## Testing Policies
After publishing, test the policy by logging in as a user with the affected role and verifying:
* They can see the records they should have access to
* They cannot see records outside their permitted scope
***
## Publishing
Security policy changes require a draft and publish cycle before taking effect.
# Security Policy Detail
## Overview
This page provides a detailed reference for the rules and conditions available when configuring Security Policies in the Designer. Security policies use Attribute-Based Access Control (ABAC) to grant or restrict access to patient data based on defined attributes.
For setup instructions, see [Setup Security Policies](/designer/security/setup-security-policies).
***
## Policy Structure
Each security policy consists of:
* **Entity** – the type of record the policy applies to (Patient, CDT record, Program, Encounter, etc.)
* **Conditions** – the rules that must evaluate to true for access to be granted
* **Actions** – what the user can do with matching records (View, Create, Edit, Delete)
***
## Condition Attributes
Conditions reference attributes of the patient, the user, or the relationship between them:
| Attribute | Description |
| ---------------------- | --------------------------------------------------------- |
| **Care Team Member** | User is on the patient's care team |
| **Primary Contact** | User is set as the patient's primary contact |
| **Region** | Patient's region matches the user's assigned region |
| **Territory** | Patient's territory matches the user's assigned territory |
| **Program Enrollment** | Patient is enrolled in a specific program |
| **Assigned To** | Patient is directly assigned to the user |
***
## Combining Conditions
Conditions can be combined with:
* **AND** – all conditions must be true
* **OR** – at least one condition must be true
Example – "Own patients in my region":
* Care Team Member = true **AND** Region = User's Region
***
## Permitted Actions
For each entity, you can grant:
* **View** – read access to the record
* **Create** – ability to create new records of this type
* **Edit** – ability to modify existing records
* **Delete** – ability to delete records (requires patient delete to be enabled)
***
## Policy Precedence
When a user has multiple policies (via multiple roles), the most permissive policy applies for each action. Welkin does not use deny-override logic.
---
[Next Page](/llms-full.txt/1)