# Awell Docs — full content # Awell documentation URL: https://docs.awellhealth.com/docs Care teams lose hours to work nobody should be doing: re-keying the same data into three systems, chasing a form that never came back, remembering who was supposed to follow up. A care flow handles that coordination. These docs cover how to build one, how to run it, and how to connect it to the systems a team already has. ## If you're new to Awell, start with 'Get Started' [#if-youre-new-to-awell-start-with-get-started] [Get started](/docs/get-started) takes fifteen minutes and explains what a care flow is, how the parts of the platform fit together, and the vocabulary the rest of these pages assume. **Care flow authors** decide what should happen, for whom, and when, in clinical and operational terms, without writing code. * [Design care flows](/docs/design-care-flows) builds them in Studio. * [Care delivery](/docs/run-care-flows) covers the day-to-day work in Awell Care and Panels. * [Improve & analyze](/docs/improve-and-analyse) shows how a live care flow is performing. * [Administer & secure](/docs/administer-and-secure) covers teams, roles, branding, and single sign-on. **Engineers** wire care flows to the systems around them, so every activity has real data behind it. * [Connect systems](/docs/connect-systems) covers electronic medical records, HL7, and calls to external APIs. * [Automate with events](/docs/automate-with-events) covers webhooks in both directions. * [Embed & host](/docs/embed-and-host) puts activities in front of patients and clinicians. * [Data & source control](/docs/data) gets data out, and versions care flows as code. * [API reference](/api-reference) has the exact queries, mutations, and fields. Both paths reach [Extensions](/docs/extensions), which is how a care flow reaches another system, and the [Marketplace](/docs/marketplace), which lists what already exists. ## Page Labels [#page-labels] A page's purpose is clear before the first paragraph. | Kind | Answers | | ------------- | ----------------------------------------------- | | **Concept** | What is this, and why does it matter? | | **How-to** | What are the steps for this one task? | | **Reference** | What are the exact fields, values, and options? | | **Tutorial** | Walk me through building something end to end. | Pages also say who they're mainly for, and a page that needs an engineer's help says where to hand off. # Set your organization's branding URL: https://docs.awellhealth.com/docs/administer-and-secure/branding Branding is set separately for the platform the care team uses and for the Hosted Pages patients see. ## Platform branding is what the care team sees [#platform-branding-is-what-the-care-team-sees] 1. Open **Settings**, at the bottom of the left navigation. 2. Open the **Branding** tab. 3. Upload the **logo** with the **Change** button. 4. Click **Save**. The Branding tab, with the organization logo and the option to change or remove it Refresh the browser and the branding appears in the sidebar. Awell Panels carries its own color setting, separate from this one. See [Set the accent color in Panels](/docs/run-care-flows/set-the-accent-color-in-panels). ## Hosted Pages branding is what patients see [#hosted-pages-branding-is-what-patients-see] A patient asked for health information on an unbranded page has no way to tell who's asking. See [Hosted Pages settings](/docs/embed-and-host/hosted-pages-settings), and [Set a custom domain](/docs/embed-and-host/set-a-custom-domain-for-hosted-pages) so the URL matches too. Hosted pages branding, with the page title and accent colour, and a live preview of the result ## Set branding in every environment [#set-branding-in-every-environment] Branding is per environment, and it's on the [go-live checklist](/docs/design-care-flows/go-live-checklist). Setting it in Sandbox does **not** set it in Production, so a live care flow can still show patients an unbranded page. ## Next steps [#next-steps] **Next:** [Set working hours for patient contact](/docs/administer-and-secure/working-hours) — the hours a care flow is allowed to reach patients. # Platform, security and compliance FAQ URL: https://docs.awellhealth.com/docs/administer-and-secure/faq Evaluating Awell usually means answering a security questionnaire, a privacy review, or a regulatory question before any care flow gets built. This page collects those answers in one place, grouped by the kind of review that asks them. For anything not covered here, email [support@awellhealth.com](mailto:support@awellhealth.com). ## Architecture and hosting [#architecture-and-hosting] ### Is there an architecture diagram of the Awell platform? [#is-there-an-architecture-diagram-of-the-awell-platform] The [security whitepaper](https://awellhealth.notion.site/Whitepaper-Awell-Security-Privacy-AI-2e08921cdb1c8051a4f6c91200ee5cb4) gives a high-level view of the platform and its components. A detailed component diagram is available on request from [support@awellhealth.com](mailto:support@awellhealth.com). ### Where is the Awell stack hosted? [#where-is-the-awell-stack-hosted] On Google Cloud. It can be deployed in several geographical regions to meet compliance requirements. ### How scalable is the platform? [#how-scalable-is-the-platform] The integrations and infrastructure are designed to handle large patient volumes. Current uptime and incident history are on the [status page](https://status.awellhealth.com/). ### How does Awell keep data inside a specific region? [#how-does-awell-keep-data-inside-a-specific-region] Deployments are regional. Data does not leave the region it is deployed in. ### Which environments are available? [#which-environments-are-available] Two customer-facing environments: Sandbox and Production. Awell runs additional internal environments to support its own development lifecycle. Base URLs for each region are listed in [Environments](/api-reference/guides/environments). Integration and testing needs beyond these two can be discussed with [support@awellhealth.com](mailto:support@awellhealth.com). ## Compliance and security [#compliance-and-security] ### Where is Awell's security documentation? [#where-is-awells-security-documentation] The [security whitepaper](https://awellhealth.notion.site/Whitepaper-Awell-Security-Privacy-AI-2e08921cdb1c8051a4f6c91200ee5cb4) covers the approach at a high level. The [trust center](https://security.awellhealth.com/) holds the detailed evidence, available on request. ### Is Awell SOC 2 certified? [#is-awell-soc-2-certified] Not yet. Awell is certified to ISO 27001, the international standard for information security management. Awell's customers include pharmaceutical and medical device companies with strict security and compliance requirements. ### Is data encrypted? [#is-data-encrypted] Yes, at rest and in transit. The database runs on a Kubernetes cluster in Google Kubernetes Engine, backed by a Kubernetes persistent volume covered by Google Cloud's default encryption of data at rest. In-cluster database connections use HTTPS and so are encrypted in transit through TLS. Unencrypted HTTP access to the database is disabled. ### How often are penetration tests and audits performed? [#how-often-are-penetration-tests-and-audits-performed] Penetration tests are scheduled annually and carried out by an external party. The information security management system is audited every year as part of the ISO 27001 certification. ### What does disaster recovery and backup look like? [#what-does-disaster-recovery-and-backup-look-like] The product runs on Google Kubernetes Engine using regional clusters, which carry built-in redundancy across three zones per region. Backups run daily in every environment. Provisioning a new environment is fully automated. If a Google data center were completely unavailable, Awell can create a deployment in a different data center and restore the latest backup within one day at most, as defined in the disaster recovery policy. In practice it can take about an hour. Replicating a deployment across separate data centers adds a further layer of redundancy and is on the technical roadmap, not yet available. ### Is multi-factor authentication required on production systems? [#is-multi-factor-authentication-required-on-production-systems] Yes, on all enterprise applications and production systems. ### Are third parties with access to customer data assessed? [#are-third-parties-with-access-to-customer-data-assessed] Yes. All third parties are reviewed annually under Awell's Supplier Security Policy, part of the information security management system audited each year for ISO 27001. Reviews cover risk assessment, background verification, contract clauses, and training and awareness. ### How is product data backed up? [#how-is-product-data-backed-up] All data is backed up daily and retained for 30 days in Google Cloud, encrypted in transit and at rest. ### What prevents malware reaching customers? [#what-prevents-malware-reaching-customers] Awell follows industry-standard practices in its web applications: HTTPS traffic only, current certificates, sanitized user input, and no third-party scripts beyond trusted partners. Under the ISO 27001 certification, all staff are required to keep their devices protected with antivirus and firewall software. ## Data privacy [#data-privacy] ### Is the platform HIPAA and GDPR compliant? [#is-the-platform-hipaa-and-gdpr-compliant] Yes. The Awell platform complies with both the Health Insurance Portability and Accountability Act and the General Data Protection Regulation. ### How is personal and health data stored? [#how-is-personal-and-health-data-stored] Personally identifiable information and protected health information are stored in a graph database, which supports orchestration, and in Google BigQuery, which supports analytics. Both run on Google Cloud. How much of that data reaches Awell is the customer's decision. The platform also works with completely anonymous patients. ### Will Awell sign a Business Associate Agreement? [#will-awell-sign-a-business-associate-agreement] Yes. ### What prevents sensitive data leaking? [#what-prevents-sensitive-data-leaking] Access to the databases holding sensitive data is deliberately narrow: no sensitive data in logs, enforced strong password rules, no shared credentials, and no public database endpoint. Internal access is granted only when needed, such as troubleshooting. Data is encrypted at rest and in transit. The ISO 27001 certification requires hardware and software controls plus staff training aimed at preventing data leaks. In multi-tenant deployments, all data is logically isolated per tenant so it cannot leak between customers. ## Usage and billing [#usage-and-billing] ### What counts as a monthly active patient? [#what-counts-as-a-monthly-active-patient] Billing is per monthly active patient, and a patient counts as active whether they did anything or not. The full definition, including what does and does not trigger it, is in [Monthly active patients](/docs/data/monthly-active-patients). ## Data [#data] ### Are data points and answers uniquely identifiable? [#are-data-points-and-answers-uniquely-identifiable] Yes. Questions can also carry a human-readable identifier to make analytics queries easier to write. ### Can custom attributes or tags be added to a care flow? [#can-custom-attributes-or-tags-be-added-to-a-care-flow] Not yet. This is on the roadmap, including making such tags available in Google BigQuery. ## AI and large language models [#ai-and-large-language-models] ### Does the platform include AI features? [#does-the-platform-include-ai-features] Yes. Shelly, Awell's CareOps analytics assistant, is built on current large language models. See [Ask Shelly about your care flows](/docs/improve-and-analyse/instant-care-flow-insights-with-shelly). ### What data does Awell send to large language model providers? [#what-data-does-awell-send-to-large-language-model-providers] Shelly can read the data in a customer's own tenant. Three measures keep personal and health data out of what reaches the model provider: 1. Shelly has no access to patient profile data. 2. Personally identifiable information that could appear in care flow data is removed first, by an entity extraction model running on Awell's own infrastructure. 3. A zero-retention policy applies to everything Shelly sends to the model provider. ### Has Awell signed a Business Associate Agreement with the model provider? [#has-awell-signed-a-business-associate-agreement-with-the-model-provider] Yes. ## Medical device compliance [#medical-device-compliance] Regulatory classification depends on what a care flow is intended to do, which makes it the customer's assessment to make. The answers below indicate where the line usually falls. They are not legal advice. ### Is the Awell platform a medical device? [#is-the-awell-platform-a-medical-device] No. The Awell platform is general software for building and operating care flows. An individual care flow built on it may be a different matter. Depending on its intended purpose, a care flow can qualify as a medical device under the EU Medical Device Regulation, known as MDR, or under the rules of the US Food and Drug Administration. In that case it may require CE certification or FDA approval. Awell recommends establishing the regulatory position before implementing a care flow. ### Does a care flow need MDR certification? [#does-a-care-flow-need-mdr-certification] A care flow that only collects information from patients and passes it to a healthcare professional most likely is not a medical device. Onboarding care flows and pre-consultation questionnaires are typical examples. A care flow designed to diagnose, monitor or treat patients most likely is. Health institutions may only need to comply with article 5(5) of MDR, covering in-house medical devices, so it is worth reading that article and the [guidance for in-house devices](https://dskb.dk/wp-content/uploads/2021/09/In-house-guidance_stakeholders.pdf) to check eligibility for that route. MDCG 2019-11 covers classification of software and is published on the European Commission's [MDCG guidance page](https://health.ec.europa.eu/medical-devices-sector/new-regulations/guidance-mdcg-endorsed-documents-and-other-guidance_en). One case catches people out. Under the [borderline manual](https://health.ec.europa.eu/system/files/2022-12/md_borderline_manual_12-2022_en.pdf) published in December 2022, any simple calculation using patient variables counts as a medical calculation, and therefore a medical device. Calculating stroke risk for patients with atrial fibrillation using the CHA₂DS₂-VASc score is one example. ### Does a care flow need FDA approval? [#does-a-care-flow-need-fda-approval] Depending on its intended purpose, a care flow may be clinical decision support software with device functions. The FDA's [Clinical Decision Support Software guidance](https://www.fda.gov/media/109618/download) gives examples to compare a care flow against, and the [Policy for Device Software Functions and Mobile Medical Applications](https://www.fda.gov/media/80958/download) covers exemptions. Awell recommends establishing the regulatory position before implementing a care flow. ### Is Awell ISO 13485 certified? [#is-awell-iso-13485-certified] No. ISO 13485 covers medical device manufacturing, and Awell does not manufacture medical devices. Awell follows industry best practices for quality. ## Next steps [#next-steps] **Next:** [Team, roles and permissions](/docs/administer-and-secure/roles-and-permissions) — security review usually moves on to who inside the organization can see and change what. # Administer & secure URL: https://docs.awellhealth.com/docs/administer-and-secure Set the organization up once, then revisit it when the team changes or new obligations apply. This section covers team membership, roles, branding, working hours, and single sign-on (SSO). ## Pages in this section, in reading order [#pages-in-this-section-in-reading-order] * [Team, roles and permissions](/docs/administer-and-secure/roles-and-permissions). Invite people and control what each role can do. * [Set your organization's branding](/docs/administer-and-secure/branding). Make what patients see look like it came from the organization. * [Set working hours for patient contact](/docs/administer-and-secure/working-hours). The hours a care flow may reach patients, and what happens to activities due outside them. * [Single sign-on](/docs/administer-and-secure/single-sign-on). What it is and how Awell supports it. * [Set up SSO](/docs/administer-and-secure/set-up-sso). The process, which starts with contacting Awell. * [SSO with Google](/docs/administer-and-secure/sso-with-google) and [SSO with Okta](/docs/administer-and-secure/sso-with-okta) for provider-specific steps. ## Where the security and compliance answers live [#where-the-security-and-compliance-answers-live] For how Navi isolates embedded activities, see [Navi architecture and security](/docs/embed-and-host). > The security, compliance and medical-device answers sit inside a single FAQ page rather than here. ## Who this is for [#who-this-is-for] This section is for account owners setting the organization up and for the engineer who connects SSO. Security and compliance content is written to be forwarded to people who don't use Awell at all. # Team, roles and permissions URL: https://docs.awellhealth.com/docs/administer-and-secure/roles-and-permissions Awell controls what people can see and do through **roles**. This page covers inviting people, managing them, and what each role allows. ## Invite a team member [#invite-a-team-member] As an **Org Admin**: 1. Open **Settings**, at the bottom of the left navigation. 2. Open the **Team** tab. 3. Click **Add team member**. 4. Fill in their personal details and email address. 5. Click **Send invite**. The Team tab, with each member's roles shown as columns grouped under Platform, Design, Operate and Manage Roles are columns, not a single choice, so one person can hold several at once. > An email address **cannot be changed** after the profile is created. The email uniquely identifies the > team member, and changing it would create inconsistencies. If someone's address changes, delete the > profile and create a new one. ## Org admins delete profiles and switch roles [#org-admins-delete-profiles-and-switch-roles] An Org Admin deletes a team member's profile when someone leaves or no longer needs access, and switches roles as someone's responsibilities change. ## Roles are additive, and one person can hold several [#roles-are-additive-and-one-person-can-hold-several] One person can hold more than one role, and their access is the **combined** permissions of all of them. Org admins manage roles from the **Settings** page. ## What each role allows [#what-each-role-allows] | Permission | Default (everyone) | Designer | Publisher | Releaser | Operator (Care) | Operator (Limited) | Org admin | | ----------------------------------- | ------------------ | -------- | --------- | -------- | --------------- | ------------------ | --------- | | Create care flow forms | ✅ | | | | | | | | Edit shared forms | | ✅ | | | | | | | Create and edit care flows | | ✅ | | | | | | | Publish care flows | | | ✅ | | | | | | Set care flows live | | | | ✅ | | | | | Promote care flows | | | | | | | see note | | Manage integrations | | | | | | | ✅ | | Monitor care flows and integrations | | | | | | | ✅ | | Improve care flows | | | | | | | ✅ | | Manage org settings | | | | | | | ✅ | | View patient list | | | | | ✅ | ✅ | | | Edit patient data | | | | | ✅ | ❌ | | | View orchestrated care flows | | | | | ✅ | ✅ | | | Access worklists | | | | | ✅ | ❌ | | A blank cell means the role doesn't grant that permission. A ❌ means the permission is explicitly withheld: Operator (Limited) can see patients but can't edit their data or work a worklist. > **One row needs verifying.** In the source table, **Promote care flows** has no role marked, while > [Sandbox to production promotion](/docs/design-care-flows/sandbox-production-promotion) states that > only **Admin** can promote, and the two can't both be right. Treat Admin-only as the working answer and > confirm with [support@awellhealth.com](mailto:support@awellhealth.com) before relying on it. ## Designing access around the publish chain [#designing-access-around-the-publish-chain] **Designer**, **Publisher** and **Releaser** are separate roles for three consecutive steps: build it, publish a version, make that version live. The split exists so clinical colleagues can design freely while release stays controlled. For a harder gate than roles provide, see [Protect care flows](/docs/data/protect-care-flows), which requires a merge in the organization's Git provider before publication. ## Next steps [#next-steps] **Next:** [Set your organization's branding](/docs/administer-and-secure/branding) — apply the organization's logo to the platform and to the pages patients see. # Set up SSO URL: https://docs.awellhealth.com/docs/administer-and-secure/set-up-sso > Single sign-on (SSO) **can't be set up from within the Awell applications**. Awell configures it on > request, so the first step is a support email rather than a settings page. ## 1. Contact Awell [#1-contact-awell] Email [support@awellhealth.com](mailto:support@awellhealth.com) to request SSO, and include: * the organization's name * the name of the identity provider (IdP), for example Okta or Google ## 2. Gather the integration details [#2-gather-the-integration-details] Setup means configuring the IdP and coordinating with Awell. Awell needs the IdP metadata, which typically includes the IdP URL and the certificate used for SSO, to establish the connection. Awell sends back the values to enter on the IdP side, which differ by provider: | Provider | Awell provides | | -------- | ------------------------------------ | | Google | ACS URL, Entity ID | | Okta | ACS URL, Audience URI, Connection ID | ## 3. Configure the identity provider [#3-configure-the-identity-provider] Follow the provider's guide: * [SSO with Google](/docs/administer-and-secure/sso-with-google) * [SSO with Okta](/docs/administer-and-secure/sso-with-okta) ## Other SAML providers are supported on request [#other-saml-providers-are-supported-on-request] Google Workspace and Okta have step-by-step guides. Other providers that use Security Assertion Markup Language (SAML) are generally supported; ask when making the request. ## Next steps [#next-steps] **Next:** the guide for [Google](/docs/administer-and-secure/sso-with-google) or [Okta](/docs/administer-and-secure/sso-with-okta). # Single sign-on URL: https://docs.awellhealth.com/docs/administer-and-secure/single-sign-on **Single sign-on (SSO)** lets an organization's people reach all of Awell's applications through its own **identity provider**, or IdP. ## What SSO gives an organization [#what-sso-gives-an-organization] Nobody has to create, remember or reuse a separate Awell password, so there's less password fatigue and less of the risk that comes with it. Sign-in is controlled in the IdP the organization already uses. Someone leaving the organization loses Awell access because they lost their IdP account, not because an administrator remembered to remove them here. ## SAML is the protocol the guides here use [#saml-is-the-protocol-the-guides-here-use] Awell supports the common SSO protocols. The provider guides in this section use **Security Assertion Markup Language**, or SAML. ## Just-in-time provisioning creates the profile at first login [#just-in-time-provisioning-creates-the-profile-at-first-login] With **just-in-time (JIT) provisioning**, a user profile is created in Awell the first time that person signs in through the IdP, rather than being created in advance. Onboarding becomes an IdP task: grant someone access to the Awell app in the IdP, and their Awell profile appears at first login. JIT creates the profile but doesn't decide which [role](/docs/administer-and-secure/roles-and-permissions) it gets, so plan how new team members get the right access. ## Next steps [#next-steps] **Next:** [Set up SSO](/docs/administer-and-secure/set-up-sso) — the setup starts with a request to Awell, not a settings page. # SSO with Google URL: https://docs.awellhealth.com/docs/administer-and-secure/sso-with-google With Google as the identity provider (IdP), people sign in to Awell with their Google credentials. The connection is a custom Security Assertion Markup Language (SAML) app in Google Workspace. ## Before starting [#before-starting] * **Google Workspace Admin Console access** with administrative privileges. * **An Awell account with permission to configure single sign-on (SSO).** Awell provides an **ACS URL** and an **Entity ID** on [request](/docs/administer-and-secure/set-up-sso). Request SSO from Awell first; step 1 can't be completed without the ACS URL and Entity ID. ## 1. Set up a SAML app in Google Workspace [#1-set-up-a-saml-app-in-google-workspace] Google's own guides cover setting up a custom SAML app and configuring the SSO profile for the organization. Use the ACS URL and Entity ID Awell provided. ## 2. Gather the SAML configuration details from Google [#2-gather-the-saml-configuration-details-from-google] Collect the details Google generates for the app, including its metadata. ## 3. Assign users in Google Workspace [#3-assign-users-in-google-workspace] Assign the app to the users and groups who should have Awell access. Once SSO is live, this becomes the ongoing access process: granting Awell access means assigning someone here, and with [just-in-time provisioning](/docs/administer-and-secure/single-sign-on) their Awell profile is created on first login. ## 4. Provide the Google metadata to Awell [#4-provide-the-google-metadata-to-awell] Send the metadata to Awell, who complete the connection on their side. ## Awell completes the connection [#awell-completes-the-connection] Awell finishes the configuration and confirms when SSO is live. Test with one user before assigning everyone. ## Next steps [#next-steps] Once people can sign in, assign them the right [roles](/docs/administer-and-secure/roles-and-permissions). SSO controls who can log in, and roles control what they can do. # SSO with Okta URL: https://docs.awellhealth.com/docs/administer-and-secure/sso-with-okta With Okta as the identity provider (IdP), people sign in to Awell with their Okta credentials. The connection is a Security Assertion Markup Language (SAML) app integration in Okta. ## Before starting [#before-starting] * **An active Okta account** with administrative access. * **An Awell account with permission to configure single sign-on (SSO).** Awell provides an **ACS URL**, an **Audience URI** and a **Connection ID** on [request](/docs/administer-and-secure/set-up-sso). Request SSO from Awell first; step 2 can't be completed without those three values. ## 1. Create and configure a new Okta application [#1-create-and-configure-a-new-okta-application] Follow Okta's guide for adding a SAML application. ## 2. Create the SAML app integration [#2-create-the-saml-app-integration] Complete the SAML integration using the ACS URL, Audience URI and Connection ID from Awell. ## 3. Gather the SAML configuration details from Okta [#3-gather-the-saml-configuration-details-from-okta] Collect the details Okta generates, including its metadata. ## 4. Assign users in Okta [#4-assign-users-in-okta] Assign the application to the users and groups who should have Awell access. As with any IdP, assigning the application is the ongoing access process: with [just-in-time provisioning](/docs/administer-and-secure/single-sign-on) an assigned user's Awell profile is created the first time they log in. ## 5. Provide the Okta details to Awell [#5-provide-the-okta-details-to-awell] Send the details to Awell, who complete the connection. ## Awell completes the connection [#awell-completes-the-connection] Awell finishes the configuration and confirms when SSO is live. Test with one user before assigning everyone. ## Next steps [#next-steps] Once people can sign in, assign them the right [roles](/docs/administer-and-secure/roles-and-permissions). # Set working hours for patient contact URL: https://docs.awellhealth.com/docs/administer-and-secure/working-hours Working hours are the times of day when a care flow may contact patients. A step or action due outside those hours is held and activated once the window opens again. With no window set, nothing is held. ## Working hours are one window for the whole organization [#working-hours-are-one-window-for-the-whole-organization] 1. Open **Settings**, at the bottom of the left navigation. 2. Open the **General** tab. 3. Under **Working hours**, choose a **Timezone**, then set **From** and **To**. 4. Click **Save**. The same window applies every day, weekends included. **Clear** removes it, after which activities activate whenever they fall due. The timezone is the organization's, not the patient's. A window of 07:00 to 20:00 in `Europe/Brussels` opens at 07:00 Brussels time for every patient in the organization, wherever they are. ## What a working-hours window moves [#what-a-working-hours-window-moves] Working hours apply to steps and actions: * Due before the window opens: activation moves to that day's opening time. * Due after the window closes: activation moves to the next day's opening time. * Due inside the window: activation is unchanged. Nothing is canceled or skipped; only the activation time moves. A [Timer](/docs/design-care-flows/the-timer-component) sets the hour of day a step activates in the patient's timezone. Working hours are applied on top of that, in the organization's timezone, so a step timed for 06:00 local waits for the window if the window opens later. While a stakeholder works through a hosted session, an activity due immediately activates straight away instead of waiting for the window, because the stakeholder is already on the page. ## Activation spreads over the first 10 minutes [#activation-spreads-over-the-first-10-minutes] Held activities don't all activate at the moment the window opens. Each care flow is assigned a fixed offset of up to 10 minutes past the opening time, so a night's held activities arrive across the first 10 minutes of the window. * A care flow's offset never changes, so it lands in the same slot every day. * Recomputing the schedule, on a retry for instance, produces the same time. * Everything held for the same care flow shares that offset, so one patient's overnight messages still arrive in one batch rather than trickling in. * Activation never moves earlier than the opening time, and never past the end of that working day. The 10-minute window is set by Awell and isn't part of organization settings. ### Example [#example] An organization sets working hours to 07:00 to 20:00 in `Europe/Brussels`. A care flow schedules a medication reminder for 03:20. The reminder is held overnight and sent at 07:04, along with anything else that care flow held. A second patient's care flow, held the same night, sends at 07:09. A care team watching a worklist sees the held activities appear across those first 10 minutes rather than in a single block at 07:00. ## Next steps [#next-steps] **Next:** [Single sign-on](/docs/administer-and-secure/single-sign-on) — how the team signs in through the organization's own identity provider. # ADT feeds URL: https://docs.awellhealth.com/docs/automate-with-events/adt-feeds An **ADT feed** carries Admission, Discharge and Transfer messages, the standard way healthcare systems tell each other about a patient's movements and status changes within a facility. Because the feed reflects where a patient actually is, it's a strong trigger: care can follow admission and discharge without anyone remembering to start a flow. ## Mirth Connect processes the feed [#mirth-connect-processes-the-feed] Awell uses **Mirth Connect** as the integration engine for ADT feeds. See [How Awell connects to other systems](/docs/connect-systems/healthcare-interoperability). Mirth is configured to intercept the hospital's ADT messages. When one arrives, Awell processes it, extracts the key patient information and identifiers, and starts, updates or stops the relevant care flow. ## The hard parts are agreements, not code [#the-hard-parts-are-agreements-not-code] Settle these with the hospital: * **Which message types** should act, and what each should do. * **Which identifier** matches the patient. See [Patient identifiers](/docs/connect-systems/patient-identifiers). * **What happens on a transfer**, as distinct from an admission or a discharge. For appointment-driven rather than admission-driven enrollment, see [Patient creation with SIU messages](/docs/connect-systems/patient-creation-with-siu-messages). ## Next steps [#next-steps] **Next:** [Trigger with the API](/docs/automate-with-events/trigger-with-the-api) for full control. # Before you trigger a care flow URL: https://docs.awellhealth.com/docs/automate-with-events/before-you-trigger-a-care-flow Several triggers can start a care flow, and nothing restricts a care flow to one of them. Each suits different situations, so running more than one is normal. Whichever trigger starts it, a care flow needs a patient and whatever data its logic reads. ## Create a patient first [#create-a-patient-first] Every care flow is linked to a patient, so the patient has to exist before the flow can start. **Anonymous patients are supported**, with no protected health information at all, which suits a public intake form where the person filling it in isn't known yet. **Populate `patient_code`.** It holds the calling system's own internal ID for the patient, and it's what matches a patient in Awell to the same person elsewhere. Skipping it makes the two records harder to match up later. See [Patient identifiers](/docs/connect-systems/patient-identifiers). ## Decide what data the flow needs at start [#decide-what-data-the-flow-needs-at-start] At start, a care flow needs: 1. **Data about the patient**, as above. 2. **Data the care flow's logic needs.** Anything a condition, a calculation or a timing reference reads. These arrive as [baseline data points](/docs/design-care-flows/enrich-your-care-flow-with-baseline-data). If the flow's logic reads a baseline value that never arrived, the flow reaches that logic and stops without raising an error. Work out what the logic needs before wiring the trigger, not after. ## Triggers, ordered by engineering effort [#triggers-ordered-by-engineering-effort] | Trigger | Engineering effort | Best when | | ----------------------------------------------------------------------------------------- | ----------------------- | -------------------------------------------------- | | [Awell Care](/docs/automate-with-events/trigger-from-awell-care) | None | A person starts flows, or a flow needs testing | | [Hosted Pages link](/docs/automate-with-events/trigger-with-a-hosted-pages-link) | Very low | Patients self-enroll from a link or QR code | | [File upload](/docs/automate-with-events/trigger-from-a-file-upload) | Very low | Batches, on a schedule | | [Incoming webhook](/docs/automate-with-events/start-a-care-flow-from-an-incoming-webhook) | Low | Another system emits an event | | [ADT feeds](/docs/automate-with-events/adt-feeds) | Medium, plus a hospital | Hospital admission and discharge should drive care | | [The API](/docs/automate-with-events/trigger-with-the-api) | Highest | The integration needs full control | ## Next steps [#next-steps] **Next:** [Enrollment triggers](/docs/automate-with-events/enrollment-triggers), the place in the app where all of this is managed. # Configure API call retries URL: https://docs.awellhealth.com/docs/automate-with-events/configure-api-call-retries When a care flow makes a REST or GraphQL [API call](/docs/connect-systems/the-api-call-action-graphql-and-rest) and the call is considered unsuccessful, Awell retries it automatically using exponential backoff. ## The defaults [#the-defaults] * a maximum of **5 attempts** * an initial delay of **2 seconds** * a maximum delay of **1 hour** For many integrations these are fine. Change them when the system being called has its own rate limits, or when a slow retry chain would leave a patient waiting. ## Care flow settings override organization settings [#care-flow-settings-override-organization-settings] Retry behavior is set either for the whole organization or for one care flow. > **Care flow settings take precedence over organization settings.** A care flow with its own > configuration ignores the organization default, so an org-level change has no effect on it. ### For the whole organization [#for-the-whole-organization] Organization settings are only available to **Admin** roles. Ask an admin on the team for access. 1. Open **Settings**, at the bottom of the left navigation. 2. Switch to the **Advanced** tab. 3. Toggle on **Customise default API call retry configuration** and adjust: * **Initial delay in ms** — the wait before the first retry * **Max delay in ms** — the ceiling on the gap between attempts * **Maximum amount of attempts** — after this, the call is resolved as failed The Advanced tab of organization settings, with the API call retry configuration switched on and the delay and attempt limits shown The delays are entered in milliseconds, so the defaults appear as `2000` and `3600000` rather than 2 seconds and 1 hour. ### For one care flow [#for-one-care-flow] 1. Go to the **Design** space in the app switcher. 2. Select the care flow. 3. Switch to the **Settings** tab. 4. Select the **API Calls** menu on the left. 5. Toggle on **Use specific configuration**, then enable or disable automated retries and adjust the values. ## Turning retries off makes transient failures permanent [#turning-retries-off-makes-transient-failures-permanent] With retries off, a single timeout or a brief outage at the other end fails the call for good. Prefer fewer attempts over none. ## Next steps [#next-steps] **Next:** [React to Healthie events](/docs/automate-with-events/react-to-healthie-events) for a worked example of a listener. # Configure webhooks for all care flows URL: https://docs.awellhealth.com/docs/automate-with-events/configure-webhooks-for-all-care-flows A webhook set up in CareOps applies to **every published care flow** at once. That saves adding the same webhook to each flow by hand, and it keeps working when someone publishes a new one. This is the organization-wide version of [Configure webhooks in Studio](/docs/automate-with-events/configure-webhooks-in-studio), which sets a webhook on a single care flow. The two add up rather than replacing each other: a care flow gets the organization's webhooks *and* its own. ## Where they live [#where-they-live] Open **Integrations** from the left navigation, then the **Outgoing webhooks** tab. The Outgoing webhooks tab in CareOps, listing one webhook by Name, Endpoint, Status, Events, Care Flows and Created On, with Public key and Create webhook buttons above it The list shows each webhook's endpoint, whether it is Active, which events it subscribes to, and which care flows it covers. ## Create one [#create-one] Click **Create webhook**. The Create webhook dialog, with an open Events dropdown listing form.submitted, activity.created, activity.updated, activity.completed, activity.deleted, activity.expired, activity.failed and data_point.collected, a Status set to Active, a field for a test endpoint, and a Headers table of key and value pairs * **Events** — choose which events to send. Pick deliberately; sending everything leaves the receiving system to work out what matters. Every event is listed in the [Webhook event catalog](/docs/automate-with-events/webhook-event-catalog). * **Status** — `Active` sends events. Switching it off pauses delivery rather than queuing it. * **Endpoint** — the HTTPS URL events are posted to. * **Test endpoint** — optional, and worth using. Point test events somewhere separate before you send anything to production. * **Headers** — custom key/value headers sent with every request, for an API key or a routing value the receiving system needs. Typing `/` in a value inserts a constant. A header with an empty key will not save. ## Verifying that Awell sent it [#verifying-that-awell-sent-it] Every outgoing webhook is signed with a **2048-bit RSA key pair** held for your organization. Awell signs with the private key and sends the signature in an `x-awell-signature` header; the receiving end verifies it with the public key. The **Public key** button on this tab shows that key as a PEM block. It is the same key for every outgoing webhook in the organization, whether it was set up here or on a single care flow — there is no per-webhook secret. A public key is not a secret. It can go in a config file or a repository like any other public key. Only the private key could forge a signature, and that never leaves Awell. Awell also only delivers to **HTTPS** endpoints, and the custom headers above are a second way for the receiver to check the source — put a token in one and validate it on arrival. See [Receive webhook events](/docs/automate-with-events/receive-webhook-events) for the verification step by step. ## Next steps [#next-steps] **Next:** [Receive webhook events](/docs/automate-with-events/receive-webhook-events) — build the endpoint on the other end, verify the signature, and handle repeats and retries. # Configure webhooks in Studio URL: https://docs.awellhealth.com/docs/automate-with-events/configure-webhooks-in-studio Webhooks let a care flow tell another system what happened. This page covers switching them on in the care flow's settings; someone technical has to build the receiving end first. ## The URL and the public key change hands first [#the-url-and-the-public-key-change-hands-first] The team receiving the events supplies **the URL** to send them to. They need **Awell's public key** back, so they can prove each message really came from Awell. ## Add a webhook to a care flow [#add-a-webhook-to-a-care-flow] 1. Open the care flow. 2. Go to its **Settings**, then **Webhooks**. 3. Add a webhook: give it a name, paste the URL, and choose which events to send. 4. Save. Choose events deliberately. Sending everything leaves the other system to work out what matters, and makes problems harder to spot. ## The public key belongs to your organization, not to one webhook [#the-public-key-belongs-to-your-organization-not-to-one-webhook] Awell signs every outgoing webhook with a private key held for your organization, and the receiving end verifies it with the matching **public key**. There is no per-webhook secret to copy: the same key verifies every outgoing webhook, however it was set up. Get it from **Integrations → Outgoing webhooks → Public key**, which shows it as a PEM block. **It is a public key, so it is not a secret.** It can go in a config file, a repository, or a ticket like any other public key. Nothing is weakened by someone else seeing it — only the private key, which never leaves Awell, could let anyone forge a signature. See [Receive webhook events](/docs/automate-with-events/receive-webhook-events) for the verification itself. ## Disabling is a pause, not a queue [#disabling-is-a-pause-not-a-queue] A webhook can be disabled without being deleted while the receiving system is down for maintenance or being changed: the configuration stays and the traffic stops. Events that happen while a webhook is disabled are not sent. ## Check whether a call arrived [#check-whether-a-call-arrived] Configuration and logs live in different places, which is the part most people get wrong. * **Integrations** is where webhooks are set up: it has an **Incoming webhooks** tab and an **Outgoing webhooks** tab. * **Monitor** is where the traffic is inspected, with **Outgoing Webhooks** and **Incoming Webhooks** each listed under it. Each call shows whether it succeeded. Filter by care flow name, care flow ID, webhook ID, patient ID, or by status, to look at just the failures. The webhook log, listing each call with its patient, care flow, time and response code, with a Retry action on every row Logs are kept for roughly **five days**, and up to **1,000 calls** — the log itself states both limits. ## Retry something that failed [#retry-something-that-failed] Once the receiving system is back up, resend a webhook call one at a time, or resend all the failed calls for a care flow at once. Awell also retries automatically when a call fails, waiting longer between each attempt. It starts at a couple of seconds and backs off for up to about **18 hours** before it stops trying, so a brief outage usually resolves without a manual retry. ## Next steps [#next-steps] * **Something isn't arriving?** Check the logs above first, then confirm the URL and the events with the receiving engineer. * **What's actually being sent?** → [Webhooks and events](/docs/automate-with-events/webhooks-and-events) * **Traffic the other way, with another system starting a care flow?** → [Start a care flow from an incoming webhook](/docs/automate-with-events/start-a-care-flow-from-an-incoming-webhook) # Enrollment triggers URL: https://docs.awellhealth.com/docs/automate-with-events/enrollment-triggers Care flows can be started in several ways: through the app, the API, webhooks, bulk enrollment and more. **Enrollment triggers** is a dedicated section in the app for seeing and managing what starts a given care flow. ## Manual enrollment is always available [#manual-enrollment-is-always-available] Every care flow can be triggered manually, either through [Awell Care](/docs/automate-with-events/trigger-from-awell-care) or the Orchestration API. This trigger is **always enabled**. It needs no setup and cannot be disabled, so every care flow has at least one way in. ## Webhook enrollment takes an extension, an integration and a trigger [#webhook-enrollment-takes-an-extension-an-integration-and-a-trigger] A care flow can be started by an event from a third-party system: 1. **Install the extension** for the system to listen to. See [Integrate with extensions](/docs/connect-systems/integrate-with-extensions). 2. **Set up an incoming webhook integration** linked to that extension. 3. **Configure the enrollment trigger**, linking the incoming webhook to it, then configure the data mapping and any trigger conditions. The Enrollment Triggers list, showing each trigger with its source, the care flow it starts, and whether it is enabled Data mapping pulls values out of the incoming payload into [baseline data points](/docs/design-care-flows/enrich-your-care-flow-with-baseline-data). Trigger conditions decide which incoming events should actually start a flow, which matters because a busy webhook will otherwise start one every time it fires. ## The other trigger types live in this section too [#the-other-trigger-types-live-in-this-section-too] Hosted Pages links, bulk enrollment and the rest are covered here, starting from [Before you trigger a care flow](/docs/automate-with-events/before-you-trigger-a-care-flow). ## Next steps [#next-steps] **Next:** [Trigger a care flow from Awell Care](/docs/automate-with-events/trigger-from-awell-care), the simplest option. # Automate with events URL: https://docs.awellhealth.com/docs/automate-with-events Webhooks run in both directions here: * **Outbound webhook**: Awell reports that something happened. A form was submitted or a care flow completed, so Awell posts an event to an endpoint the receiving system owns. * **Incoming webhook**: another system asks Awell to do something. A booking is confirmed elsewhere, so that system posts to an Awell URL and a care flow starts. The direction is easy to get the wrong way around, so every page here says which one it covers. ## Read these in order [#read-these-in-order] 1. [Webhooks and events](/docs/automate-with-events/webhooks-and-events) What they are, both directions, and what a payload contains. 2. [Receive webhook events](/docs/automate-with-events/receive-webhook-events) Build and secure an endpoint, then take it live. (For engineers.) 3. [Configure webhooks in Studio](/docs/automate-with-events/configure-webhooks-in-studio) Turn them on, get the signing secret, and monitor what was sent. (No code.) 4. [Start a care flow from an incoming webhook](/docs/automate-with-events/start-a-care-flow-from-an-incoming-webhook) The other direction: something outside Awell begins care. 5. [Webhook event catalog](/docs/automate-with-events/webhook-event-catalog) Every event available to subscribe to. # React to Healthie events with your own listener URL: https://docs.awellhealth.com/docs/automate-with-events/react-to-healthie-events An Awell care flow can react to a Healthie webhook event through the extension's built-in events, or through a custom listener that takes more work and gives more control. ## Option 1: the Healthie extension's built-in events [#option-1-the-healthie-extensions-built-in-events] Enable webhooks on the Healthie extension in Awell. These Healthie events can start a new care flow: * `appointmentCreated` * `patientCreated` If one of those is the trigger, nothing else is needed. See [Integrate with extensions](/docs/connect-systems/integrate-with-extensions). ## Option 2: a custom listener, for everything else [#option-2-a-custom-listener-for-everything-else] Build a listener that sits between Healthie and Awell and decides: * **which events** should trigger anything at all * **what action** to take against the Orchestration API, such as creating a patient Use this for events the extension doesn't cover, or when the decision about what to do is more complicated than "start a flow". ### A worked example with AWS Lambda [#a-worked-example-with-aws-lambda] An HTTP request from Healthie invokes the function, which then: 1. **Receives the webhook.** The handler is called with the incoming event and the Lambda context. The event carries the full webhook payload. 2. **Logs the event.** Write the payload to the logs before doing anything with it, so there's a record of what actually arrived when the integration misbehaves. 3. **Decides whether to act**, based on the event type and its contents. 4. **Calls the Orchestration API** to do the thing, for example creating a patient or starting a care flow. See [the API reference](/api-reference). ## Verify that the request came from Healthie [#verify-that-the-request-came-from-healthie] A listener is a public endpoint, so check that a request is genuine before acting on it, the same way as for [Awell's own webhooks](/docs/automate-with-events/receive-webhook-events). ## Next steps [#next-steps] * [Awell and Healthie](/docs/connect-systems/awell-healthie) for the wider integration. * [Receive webhook events](/docs/automate-with-events/receive-webhook-events) for Awell's outbound side. # Receive webhook events URL: https://docs.awellhealth.com/docs/automate-with-events/receive-webhook-events These steps cover building an endpoint that receives events from Awell, from picking the events worth acting on to registering a production URL. For the concepts first, read [Webhooks and events](/docs/automate-with-events/webhooks-and-events). To switch webhooks on for a care flow without writing any code, see [Configure webhooks in Studio](/docs/automate-with-events/configure-webhooks-in-studio) instead. ## 1. Subscribe only to events worth acting on [#1-subscribe-only-to-events-worth-acting-on] Start from the [event catalog](/docs/automate-with-events/webhook-event-catalog) and subscribe only to what the integration will act on. Every extra event is traffic to authenticate, log, and ignore. ## 2. Create an endpoint [#2-create-an-endpoint] The endpoint needs a URL that accepts `POST` over HTTPS. Plain HTTP is not supported; the transport is part of how the payload stays private. Do as little as possible before acknowledging: verify the request, put the work on a queue, respond. A slow handler causes a retry, which arrives as a duplicate. ## 3. Verify the request came from Awell [#3-verify-the-request-came-from-awell] A URL that accepts anonymous POSTs will eventually receive something Awell didn't send. Awell signs every request, so the receiver can tell a genuine request from a forged one. ### Check the signature [#check-the-signature] Awell signs each request with a **2048-bit RSA private key** held for your organization, and sends the signature in an `x-awell-signature` header. You verify it with the matching public key. This is asymmetric signing, so there is nothing to recompute and no shared secret to compare against — you hand the signature, the body and the public key to your platform's RSA verification function and it answers yes or no. 1. Read the signature from the `x-awell-signature` header. 2. Verify it against the **raw** request body. Parsing to JSON first can change bytes and fail a signature that was actually valid. 3. If verification fails, reject the request and don't process it. The public key comes from **Integrations → Outgoing webhooks → Public key** and is the same for every outgoing webhook in your organization — it is not issued per webhook. See [Configure webhooks in Studio](/docs/automate-with-events/configure-webhooks-in-studio) for handing it over, and [Configure webhooks for all care flows](/docs/automate-with-events/configure-webhooks-for-all-care-flows) for where to find it. Being a public key, it is not a secret and needs no special handling. The private key never leaves Awell. > Verify the signature **before** trusting anything in the payload, including identifiers headed for a > lookup; every step after this one assumes the request is genuine. ### An address allowlist is a second layer, not a replacement [#an-address-allowlist-is-a-second-layer-not-a-replacement] Signature verification is the strong control. Restricting which addresses may reach the endpoint, where the infrastructure allows it, is a reasonable second layer. ## 4. Return the right response [#4-return-the-right-response] Return a `2xx` status as soon as the event is accepted. Anything else tells Awell the delivery failed, and it gets retried. Acknowledge *accepting* the work, not *finishing* it. If a downstream system is slow, respond first and process asynchronously. ## 5. Handle repeats and out-of-order arrival [#5-handle-repeats-and-out-of-order-arrival] Because delivery can repeat and order isn't guaranteed: * Make handling **idempotent**. Every delivery carries an `Idempotency-Key` header that keeps the same value on each retry of that delivery; key on it, or on the event's identifiers, so processing twice is harmless. See [Idempotent requests](/api-reference/guides/idempotency#outgoing-api-calls-and-webhooks). * Don't infer sequence from arrival order. ## 6. Test against a separate endpoint first [#6-test-against-a-separate-endpoint-first] Point a webhook at a test endpoint and confirm the whole path: signature verification passes, the `2xx` comes back quickly, and the handler does the right thing with a real payload. Keep test and production endpoints separate, so live patient events never reach a staging listener. ## 7. Go live [#7-go-live] When the test endpoint behaves, register the production URL in the care flow's settings. Check the logs after the first real events arrive rather than assuming success. [Configure webhooks in Studio](/docs/automate-with-events/configure-webhooks-in-studio) covers where to look and how to retry a failure. ## A worked example [#a-worked-example] For an end-to-end example with a specific vendor (receiving events and acting on them in an AWS Lambda), see the Healthie listener guide in **Connect systems**. ## Next steps [#next-steps] **Next:** [Configure webhooks in Studio](/docs/automate-with-events/configure-webhooks-in-studio). With the endpoint ready, turn the webhook on and check the first deliveries. # Start a care flow from an incoming webhook URL: https://docs.awellhealth.com/docs/automate-with-events/start-a-care-flow-from-an-incoming-webhook An incoming webhook is a URL. When another system posts to it, Awell starts a care flow. It's the right trigger when something outside Awell should begin care: a booking is confirmed, a patient is discharged, a form is completed elsewhere. This is the **opposite direction** from the events Awell sends out. For an endpoint that *receives* from Awell, see [Receive webhook events](/docs/automate-with-events/receive-webhook-events) instead. ## Only a published care flow can be started [#only-a-published-care-flow-can-be-started] Publish the care flow before creating the webhook. ## Create the webhook [#create-the-webhook] 1. Open **Integrations** from the left navigation, then the **Incoming webhooks** tab. 2. Click **Create webhook**. 3. Name it and choose which care flow it should start. A care flow with no required baseline data points can be enabled right away; otherwise, map them first. ### An extension can supply the events instead [#an-extension-can-supply-the-events-instead] The Create Webhook screen asks for a **Webhook Type**. As well as posting to a URL yourself, you can choose **Extension webhook** and subscribe to events an installed extension already exposes — so a booking or discharge event reaches Awell through the extension rather than through an endpoint you build and maintain. The Create Webhook screen for incoming webhooks, with Webhook Type set to Extension webhook, a Webhook Name field, and an open Extension dropdown listing installed extensions including Elation, Rest, Hubspot, Freshsales, Freshdesk, West Fax, Landing Ai and Athenahealth The dropdown lists the extensions **your organization has installed**, so what you see depends on that. See [Marketplace](/docs/marketplace) for what is available, and [What are Awell extensions](/docs/extensions/what-are-awell-extensions) for how extensions work. ## Map payload data to baseline data points [#map-payload-data-to-baseline-data-points] Baseline data points are the values a care flow needs before it can start, such as a date of birth or a referral reason. Mapping fields from an incoming payload to a care flow's baseline data points 1. Click **Test link** to send a test request to the endpoint. The payload appears on the page within a minute. 2. Use [JSONPath](https://github.com/json-path/JsonPath) to pick values out of the payload and assign each to a baseline data point. 3. Send another test payload once everything is mapped. 4. Awell checks whether the mapping is valid and sufficient to start the care flow. 5. If validation passes, enable the webhook. > **Required data points are enforced.** If a required baseline data point has no mapping, the request > is rejected rather than starting a partial care flow. ## Requests start an anonymous patient unless the payload names one [#requests-start-an-anonymous-patient-unless-the-payload-names-one] By default, every request starts a care flow for an anonymous patient, which is often fine: on an intake form the person may not be known yet. To create a patient instead, or to start a care flow for someone who already exists, include an identifier in the payload: ```json { // rest of the payload "patient_identifier": { "system": "{{IDENTIFIER_SYSTEM}}", "value": "{{IDENTIFIER_VALUE}}" } } ``` Set up the identifier system in settings first. See patient identifiers in **Connect systems**. ## Filtering happens on the trigger, not on the endpoint [#filtering-happens-on-the-trigger-not-on-the-endpoint] The webhook URL accepts every request that reaches it. Trigger conditions on the linked [enrollment trigger](/docs/automate-with-events/enrollment-triggers) then decide whether a request starts a care flow, evaluated against the mapped payload. Conditions can only test what the payload contains, so the calling system still has to send a reasonably uniform payload and call only when a care flow should begin. Where the caller can't be that precise, the workaround sits inside the care flow: conditional logic as an eligibility check that stops the flow early. Email [support@awellhealth.com](mailto:support@awellhealth.com) for help; there are ways to do it with little or no impact on the monthly active patient count. ## The logs show every request and why it was rejected [#the-logs-show-every-request-and-why-it-was-rejected] 1. Click **View logs**. 2. Filter by request status, incoming webhook name, or care flow name. 3. Click **View details** on a request to see its payload and status. The incoming webhook logs page ### What each status means [#what-each-status-means] | Status | Meaning | | ------------ | -------------------------------------------------------------------------------------------- | | `SCHEDULED` | The payload has all required baseline data points, and the request is queued for processing. | | `PROCESSING` | The scheduled request is being processed. | | `SUCCESS` | The care flow was triggered. The log includes the care flow ID and patient ID. | | `REJECTED` | Something is wrong with the payload, or the webhook is disabled. Awell rejected the request. | | `FAILED` | The request failed during processing. | | `TEST` | A test payload. Awell validated it and, if it would have been rejected, shows why. | `REJECTED` means Awell declined the request; `FAILED` means it was accepted and then broke during processing. A rejection usually points to a mapping or payload problem, and a failure is worth reporting to [support@awellhealth.com](mailto:support@awellhealth.com). ## Next steps [#next-steps] * **Other ways to start a care flow** → see the trigger types in this section. * **Monitoring incoming webhooks** → [Configure webhooks in Studio](/docs/automate-with-events/configure-webhooks-in-studio) * **What Awell sends out** → [Webhooks and events](/docs/automate-with-events/webhooks-and-events) # Trigger from a file upload URL: https://docs.awellhealth.com/docs/automate-with-events/trigger-from-a-file-upload This trigger starts care flows from files uploaded to an FTP server Awell provisions. It takes practically no engineering effort and starts **many care flows in one batch**. > Not to be confused with [collecting files and images](/docs/design-care-flows/file-upload), which is a > form question type. This page is about a file that *starts* care flows. ## Awell polls the server and starts the flows it finds [#awell-polls-the-server-and-starts-the-flows-it-finds] 1. **Awell provisions a secure FTP server** and provides the login credentials. 2. **Files arrive as CSV** (or a similar format), in a structure agreed in advance. 3. **Awell polls the server periodically**, for example hourly. When it finds a new file it processes it and starts the required care flows. 4. **Awell handles the patient side**: checking whether the patient already exists, creating the record if not, then starting the flow. 5. **Awell keeps logs** for auditability. Monitor's data ingestion view, listing each uploaded file with its status, success rate, record count and processing time **Monitor → Data Ingestion** is where those runs are reviewed, per file. Polling is the part to design around: enrollment happens on the poll interval rather than the moment the file lands. If a flow needs to start within seconds, use a [webhook](/docs/automate-with-events/start-a-care-flow-from-an-incoming-webhook) instead. ## Best for scheduled batches and systems that can't call an API [#best-for-scheduled-batches-and-systems-that-cant-call-an-api] * A batch of patients enrolls on a schedule, for example a weekly list from another team. * The source system can produce a file but can't call an API. * The audit trail a file leaves behind is worth having. ## Agree the format first [#agree-the-format-first] Agree the file format before the first upload: which columns map to which baseline data points, what identifies the patient, and what happens to a malformed row. ## Next steps [#next-steps] **Next:** [ADT feeds](/docs/automate-with-events/adt-feeds) for hospital-driven enrollment. # Trigger a care flow from Awell Care URL: https://docs.awellhealth.com/docs/automate-with-events/trigger-from-awell-care **Awell Care** is the application Awell builds and maintains for running the care flows designed in Studio. It's a prebuilt alternative to running Orchestration headless behind a custom interface. To trigger a care flow here, create a patient, then start a flow for them. ## Start a care flow [#start-a-care-flow] 1. [Create a patient](/docs/run-care-flows/create-patients) in Awell Care. 2. Start a care flow from their profile. See [Start a care flow](/docs/run-care-flows/start-a-care-flow). ## Best when there's no provider app, or a flow needs testing [#best-when-theres-no-provider-app-or-a-flow-needs-testing] * **There's no provider-facing app**, or Awell provides the interface. * **A care flow needs testing.** This is the fastest way to run a flow end to end and watch what it does, without wiring up a trigger first. Even teams that will trigger everything through the API can use Awell Care to prove a care flow works by hand before automating the way in. ## Next steps [#next-steps] **Next:** [Trigger with a Hosted Pages link](/docs/automate-with-events/trigger-with-a-hosted-pages-link) to let patients enroll themselves. # Trigger with a Hosted Pages link URL: https://docs.awellhealth.com/docs/automate-with-events/trigger-with-a-hosted-pages-link Awell can generate a shareable link for a published care flow. Clicking it **starts a care flow and immediately returns a URL to Hosted Pages**, so whoever clicked lands directly in their activities. ## Best when patients enroll themselves and start straight away [#best-when-patients-enroll-themselves-and-start-straight-away] * **Patients self-enroll.** A button on a website or in an app starts an intake or onboarding flow. * **Feedback is instant.** Because the patient initiates it, Hosted Pages appears straight away and they can complete their activities in the same visit rather than waiting for an email. ## Generate the link, or download it as a QR code [#generate-the-link-or-download-it-as-a-qr-code] Awell Studio generates a shareable Hosted Pages link for a published care flow. See [Embed & host](/docs/embed-and-host) for the hosted pages settings. **The link can also be downloaded as a QR code**, so a patient can scan it from printed material or a poster to start a care flow. ## Start a session programmatically [#start-a-session-programmatically] One mutation starts a care flow and a Hosted Pages session in a single call and returns the session URL. See [Hosted sessions in the API reference](/api-reference/reference/hosted-sessions). Use this when the calling application should control when and how the patient is handed over. ## One link per care flow, and duplicates don't inherit it [#one-link-per-care-flow-and-duplicates-dont-inherit-it] A Hosted Pages sharing link belongs to one care flow, and it is **not** copied when a care flow is [duplicated](/docs/design-care-flows/duplicate-a-care-flow). Generate a new link for the duplicate. ## Next steps [#next-steps] **Next:** [Trigger from a file upload](/docs/automate-with-events/trigger-from-a-file-upload) for starting flows in batches. # Trigger with the API URL: https://docs.awellhealth.com/docs/automate-with-events/trigger-with-the-api Triggering care flows through the API is **the most flexible method**, covering the widest range of situations. It also needs technical work, so budget engineering time for it rather than treating it as configuration. ## Search, create, then start [#search-create-then-start] 1. **Search for the patient**, to avoid creating a duplicate. See [Patients in the API reference](/api-reference/reference/patients). 2. **Create the patient** if they don't exist yet. Same reference. 3. **Start the care flow.** See [Care flows in the API reference](/api-reference/reference/care-flows). Skipping step 1 is how the same person ends up in Awell twice. Search by business identifier rather than by name. ## Starting by identifier keeps Awell IDs out of the calling system [#starting-by-identifier-keeps-awell-ids-out-of-the-calling-system] A care flow can be started with a business identifier instead of the Awell patient ID, so the calling system never has to store an Awell ID. See [Patient identifiers](/docs/connect-systems/patient-identifiers). ## When to use it [#when-to-use-it] * The other triggers don't give enough control. * Enrollment logic lives outside Awell and should stay there. * An API integration already exists for other reasons. If none of those apply, one of the lower-effort triggers in this section probably fits better. See [Before you trigger a care flow](/docs/automate-with-events/before-you-trigger-a-care-flow). ## Next steps [#next-steps] **Next:** [Configure API call retries](/docs/automate-with-events/configure-api-call-retries) for what happens when a call from a care flow fails. # Webhook event catalog URL: https://docs.awellhealth.com/docs/automate-with-events/webhook-event-catalog The events available to subscribe to when configuring an outbound webhook. Each fires once, when the thing it describes happens. Payloads carry **identifiers, not clinical detail**: the care flow, the patient, and the object the event concerns. Fetch the detail through the API using those identifiers. See [Webhooks and events](/docs/automate-with-events/webhooks-and-events) for why. ## Activities [#activities] An activity is a single thing to be done or shown: a form to complete, a message to read. | Event | Fires when | | -------------------- | ------------------------------------------------ | | `activity.created` | A new activity is created in a care flow | | `activity.completed` | An activity is finished | | `activity.updated` | An existing activity changes | | `activity.expired` | An activity passes its expiry without completion | | `activity.failed` | An activity could not be carried out | | `activity.deleted` | An activity is removed | `activity.completed` is the event to start from. ## Care flows [#care-flows] | Event | Fires when | | ------------------- | ---------------------------------------- | | `pathway.started` | A care flow starts for a patient | | `pathway.completed` | A care flow reaches its end | | `pathway.stopped` | A care flow is stopped before completing | | `pathway.deleted` | A care flow is removed | **Note the event names.** These use `pathway`, not `care_flow`. The product renamed *pathway* to *care flow*; the wire format did not follow. Subscribe to the names in the table — they are what the platform sends and what the event picker in Studio lists. Subscribe to both `pathway.completed` and `pathway.stopped` to tell a care flow that finished from one that was stopped early. ## Tracks [#tracks] A track groups related steps inside a care flow. | Event | Fires when | | ----------------- | ------------------------ | | `track.started` | A track begins | | `track.completed` | A track finishes | | `track.stopped` | A track is stopped early | ## Data and forms [#data-and-forms] | Event | Fires when | | ----------------------- | ----------------------------- | | `form.submitted` | A form response is submitted | | `data_point.collected` | A data point receives a value | | `clinical_note.created` | A clinical note is created | `form.submitted` fires once per submission; `data_point.collected` fires per value, so one submission can produce several. ## Sessions and reminders [#sessions-and-reminders] | Event | Fires when | | ------------------- | ----------------------------- | | `session.started` | A hosted-pages session begins | | `session.completed` | A session finishes | | `session.expired` | A session expires unused | | `reminder.created` | A reminder is generated | ## Patients [#patients] | Event | Fires when | | ----------------- | --------------------------- | | `patient.created` | A patient record is created | | `patient.updated` | A patient record changes | | `patient.deleted` | A patient record is deleted | ## Subscribe to what gets acted on, nothing more [#subscribe-to-what-gets-acted-on-nothing-more] Every extra event is traffic to authenticate, log, and then ignore, and it makes a real problem harder to see. A reasonable default is `activity.completed` plus `pathway.completed`, then more once the integration proves what it needs. ## Next steps [#next-steps] **Next:** [Receive webhook events](/docs/automate-with-events/receive-webhook-events), build the endpoint that handles the events chosen here. # Webhooks and events URL: https://docs.awellhealth.com/docs/automate-with-events/webhooks-and-events A webhook is a message one system sends another when something happens, so nobody has to sit and check. Awell uses them in both directions. ## Outbound webhooks report events; incoming webhooks start or advance care flows [#outbound-webhooks-report-events-incoming-webhooks-start-or-advance-care-flows] The Incoming webhooks tab under Integrations, listing each webhook with the extension and event that drives it | | What happens | What it takes | | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | **Outbound** (Awell → another system) | Something happens in a care flow (a form is submitted, a care flow completes) and Awell posts an event to a URL the other system owns | A URL that can receive the message. See [Receive webhook events](/docs/automate-with-events/receive-webhook-events) | | **Incoming** (another system → Awell) | Something happens in *that* system (a booking, a discharge) and it posts to an Awell URL to start or advance a care flow | A configured trigger. See [Start a care flow from an incoming webhook](/docs/automate-with-events/start-a-care-flow-from-an-incoming-webhook) | Each page here says which direction it covers. The rest of this page is about **outbound** events. ## An event reports one thing, once [#an-event-reports-one-thing-once] `activity.completed` means a particular activity finished. It says nothing about what else changed, and nothing about what comes next. Every event carries the identifiers needed to look up the detail through the API: the care flow, the patient, and the object the event is about. See the [webhook event catalog](/docs/automate-with-events/webhook-event-catalog) for the full list. ## Payloads carry identifiers, not clinical detail [#payloads-carry-identifiers-not-clinical-detail] Payloads are deliberately lean: they identify what happened and what it happened to, and they are **not** a copy of the patient record. Keeping identifiers rather than clinical detail in transit limits what is exposed if an endpoint is ever misconfigured. Fetch the detail with the API using the identifiers in the event. ## Delivery repeats, arrives out of order, and retries on failure [#delivery-repeats-arrives-out-of-order-and-retries-on-failure] What that means for a listener: * **Order isn't guaranteed.** Events can arrive out of sequence. Don't infer state from arrival order: read the event's own data. * **Delivery can repeat.** The same event can arrive more than once, so handling must be idempotent: processing it twice should have the same result as once. * **Failures are retried.** Awell retries with an increasing delay rather than giving up immediately. ## Next steps [#next-steps] * **Building the listener?** → [Receive webhook events](/docs/automate-with-events/receive-webhook-events) * **Turning webhooks on for a care flow?** → [Configure webhooks in Studio](/docs/automate-with-events/configure-webhooks-in-studio) * **Want the event list?** → [Webhook event catalog](/docs/automate-with-events/webhook-event-catalog) # Care flow components as code URL: https://docs.awellhealth.com/docs/data/components When a care flow syncs to the repository, its components are written as **JSON files** in a fixed folder structure. > **This structure is experimental.** Awell may change it substantially without prior notice, so don't > build tooling that depends on the exact shape without expecting to maintain it. ## Folder structure: one file per component kind [#folder-structure-one-file-per-component-kind] ``` repository ├── actions/actions.json ├── data_point_definitions/data_point_definitions.json ├── labels/labels.json ├── messages/messages.json ├── pathways/pathways.json ├── rules/rules.json ├── settings/settings.json ├── stakeholders/stakeholders.json ├── steps/steps.json └── … ``` The split keeps a diff readable: a change to a message shows up in `messages.json` rather than buried in one enormous document. ## What the files contain [#what-the-files-contain] * **actions**. The actions in the care flow, including API calls. * **data\_point\_definitions**. The data point definitions, matching the [data catalog](/docs/data/data-catalog). * **messages**. Message content. * **pathways**. The care flow definition itself. * **rules**. The conditional logic. * **settings**. Care flow settings. * **stakeholders**. Who the care flow's actions are assigned to. * **steps**. The steps and their structure. * **labels**. The [step labels](/docs/design-care-flows/label-your-steps). The folder names use Awell's internal vocabulary: `pathways` holds what the product now calls care flows. See [Key terms](/docs/get-started/key-terms). ## Editing these files does not change the care flow [#editing-these-files-does-not-change-the-care-flow] The sync is one-way. See [How syncing works](/docs/data/syncing-to-scm). ## Next steps [#next-steps] Back to [Data & source control](/docs/data). # Configure and use your data catalog URL: https://docs.awellhealth.com/docs/data/configure-use-your-data-catalog Once a care flow has some steps and forms in it, go through the [data catalog](/docs/data/data-catalog) and check that the data points are consistent and used as intended before publishing. ## Each data point shows its source, key and type [#each-data-point-shows-its-source-key-and-type] Open a data point to see those details. ## Flag personally identifiable data while building, not afterward [#flag-personally-identifiable-data-while-building-not-afterward] Mark a data point as **personally identifiable information**, or PII. The flag governs how that data is handled downstream, so set it when the data point is created rather than after the data has already flowed onward. ## Add metadata while the meaning is still fresh [#add-metadata-while-the-meaning-is-still-fresh] Attach metadata to captured data points, so the meaning travels with the value. A data point named `score_2` with no metadata can't be interpreted by whoever analyzes it a year later. ## Export the catalog for people who don't work in Studio [#export-the-catalog-for-people-who-dont-work-in-studio] Copy the export out of the catalog to review a whole care flow's data with someone who doesn't use Studio, or to hand an analyst the field list before they write queries. ## Next steps [#next-steps] **Next:** [Source Control](/docs/data/source-control) for versioning the care flow itself. # Data catalog URL: https://docs.awellhealth.com/docs/data/data-catalog The **data catalog** lists every data point registered in a care flow, in one place. It answers "what does this care flow actually collect", which gets hard once a flow has a few dozen forms and calculations in it. ## Find it on the care flow's Data catalog tab [#find-it-on-the-care-flows-data-catalog-tab] Open the care flow and go to its **Data catalog** tab. ## Every data point, with the source it came from [#every-data-point-with-the-source-it-came-from] Each entry names its source: a form question, a baseline data point, an API call response, or a system-generated value such as a calculation result or a step completion time. ## Confirming keys, spotting duplication, checking consistency [#confirming-keys-spotting-duplication-checking-consistency] * **Confirming a key** when configuring conditional logic or a variable. * **Spotting duplication.** The same real-world value collected twice under two names is easy to create and hard to notice anywhere else. * **Checking consistency** before go-live, especially across forms built by different people. Duplication is why the catalog is worth a care flow author's time as much as an engineer's. ## Next steps [#next-steps] **Next:** [Configure and use your data catalog](/docs/data/configure-use-your-data-catalog) for the parts of it that can be edited. # Data schema URL: https://docs.awellhealth.com/docs/data/data-schema Awell's data repository separates the templates designed in Studio from the patient-specific instances created from them. Which of the two a query targets decides what it counts. ## Definitions are templates, instances belong to patients [#definitions-are-templates-instances-belong-to-patients] ### Care flow definition vs care flow [#care-flow-definition-vs-care-flow] A **care flow definition** is the template designed in Studio. It describes the structure and components of a care plan and isn't tied to any patient. A **care flow** is a patient-specific instance derived from that definition. So for a definition named "post-operative follow-up", every enrolled patient has their **own** care flow derived from it. Query definitions to ask about the design; query care flows to ask about patients. ### Data point definition vs data point [#data-point-definition-vs-data-point] The same distinction one level down. A **data point definition** is the component designed in Studio, for example "patient weight". A **data point** is one patient's value, for example 80 kg. Getting these the wrong way around produces queries that look right and count the wrong thing: definitions count how many *fields exist*, data points count how many *answers were given*. ## Data point keys come from the identifier set in Studio [#data-point-keys-come-from-the-identifier-set-in-studio] Instead of randomly generated IDs, a data point definition carries a **human-readable identifier** set in Studio. In the data repository that identifier is combined with its **source** to form a **key**. So [encoding questions](/docs/design-care-flows/encode-questions-and-answer-options) pays off in analysis as well as in care flow logic: the key set at design time is the key a query runs against later. ## Release and version are not the same thing [#release-and-version-are-not-the-same-thing] A care flow definition has both, so check which one a query needs: filtering on the wrong one changes the denominator without any error. ## BigQuery holds the authoritative column list [#bigquery-holds-the-authoritative-column-list] Tables cover care flow definitions, care flows, data points, activities and related entities. Explore them in [BigQuery Studio](/docs/data/getting-access), where the current column lists are authoritative. > Columns change, so this page describes the model rather than reproducing every column. If a query > depends on an exact column, check it in BigQuery. ## Next steps [#next-steps] **Next:** [Monthly active patients](/docs/data/monthly-active-patients) — the definition Awell bills on. # Deploy care flows URL: https://docs.awellhealth.com/docs/data/deploy-care-flows Deploy care flows to any of Awell's default environments, **sandbox** or **production**, or to a custom environment, directly from a CI/CD pipeline. Through [Source Control](/docs/data/source-control), the same pipeline that ships the application can promote a care flow. ## When a pipeline beats clicking publish [#when-a-pipeline-beats-clicking-publish] * Care flow releases should follow the same process as code releases. * Deployment should be an automated, auditable step rather than someone clicking publish. * The target is a custom environment that isn't Awell's sandbox or production. To promote by hand instead, see [Sandbox to production promotion](/docs/design-care-flows/sandbox-production-promotion). > **The mechanics of wiring this into a pipeline aren't documented yet.** For help setting it up, email > [support@awellhealth.com](mailto:support@awellhealth.com). ## Next steps [#next-steps] **Next:** [Care flow components as code](/docs/data/components) for what lands in the repository. # Get access to BigQuery URL: https://docs.awellhealth.com/docs/data/getting-access How to access the BigQuery datasets depends on where the data gets explored: in Google's tooling, or in the organization's own. ## BigQuery Studio, for working in Google's tooling [#bigquery-studio-for-working-in-googles-tooling] Awell can invite an analyst to BigQuery Studio, where they discover, explore and analyze Awell datasets using BigQuery's own interfaces. **This requires a Google account** for each person who needs access. This suits analysts who work in BigQuery directly, and anyone exploring a dataset before deciding what to build on it. ## Service accounts, for connecting an external BI tool [#service-accounts-for-connecting-an-external-bi-tool] **Use this to connect an external BI tool or data platform.** The service account provides credentials for a secure, **read-only** connection between that tooling and the BigQuery datasets. Read-only is deliberate: a BI tool can't alter care flow data. ## Awell provisions access on request [#awell-provisions-access-on-request] Email [support@awellhealth.com](mailto:support@awellhealth.com) with the option needed and who needs access. ## Next steps [#next-steps] **Next:** [Data schema](/docs/data/data-schema) — read it before writing a first query. # Getting data out of Awell URL: https://docs.awellhealth.com/docs/data/getting-data-out-of-awell Care flow data comes out as a stream of events or as a query against the data repository, and the two answer different questions. ## Stream events as they happen [#stream-events-as-they-happen] Use [webhooks](/docs/automate-with-events/webhooks-and-events) to track events happening in Awell and send them on to Segment, Amplitude, Google Analytics, or an in-house service. Use this when something should happen **because** an event occurred. It's a near-real-time push that carries identifiers rather than full records. ## Query the data repository [#query-the-data-repository] Awell uses **BigQuery** as its data repository, storing and indexing care flow datasets. To query it: * **connect an external BI tool** to the BigQuery datasets, or * **use BigQuery Studio** to explore and visualize the data directly. Use this to analyze across patients and time, rather than to react to one thing. ## Use both, for different jobs [#use-both-for-different-jobs] | | Webhooks | BigQuery | | -------- | ------------------------- | ------------------------------- | | Shape | Push, event by event | Pull, query across everything | | Timing | Near real-time | Batch | | Good for | Triggering work elsewhere | Reporting, analysis, dashboards | Don't reach for BigQuery to drive a real-time action, or for webhooks to build a report. ## Next steps [#next-steps] **Next:** [Get access to BigQuery](/docs/data/getting-access). # Data & source control URL: https://docs.awellhealth.com/docs/data This section covers knowing what data a care flow produces and getting it out, and treating the care flows themselves as something to version and review. ## Getting data out [#getting-data-out] * [Getting data out of Awell](/docs/data/getting-data-out-of-awell). The strategies available. * [Get access to BigQuery](/docs/data/getting-access). BigQuery Studio, or a service account for external BI tools. * [Data schema](/docs/data/data-schema). The tables, and the definition-versus-instance distinction that everything else depends on. * [Monthly active patients](/docs/data/monthly-active-patients). What counts as active, and therefore what Awell bills on. ## Knowing what a care flow collects [#knowing-what-a-care-flow-collects] * [Data catalog](/docs/data/data-catalog). What it lists. * [Configure and use your data catalog](/docs/data/configure-use-your-data-catalog). PII flags, metadata, exports. ## Care flows as code [#care-flows-as-code] * [Source Control](/docs/data/source-control). What it is and when to use it. * [Set up Source Control](/docs/data/set-up-source-control). GitHub and GitLab. * [How syncing works](/docs/data/syncing-to-scm). One repository per care flow, and a one-way sync. * [Protect care flows](/docs/data/protect-care-flows). Require a merge before publication. * [Deploy care flows](/docs/data/deploy-care-flows). From a CI/CD pipeline. * [Care flow components as code](/docs/data/components). The JSON that lands in the repository. ## Who this is for [#who-this-is-for] Engineers and analysts. The data catalog is worth a care flow author's time too: it's the one place where the same value collected twice under two names becomes obvious. # Monthly active patients (MAPs) URL: https://docs.awellhealth.com/docs/data/monthly-active-patients A **monthly active patient**, or MAP, is a patient for whom Awell Orchestration performed an activity that month. Awell bills for Awell **Orchestration**, not for Awell Studio. So designing, validating and previewing care flows costs nothing in MAPs; running them for patients does. ## One Orchestration action makes a patient active for the month [#one-orchestration-action-makes-a-patient-active-for-the-month] A patient is active if Awell Orchestration did **at least one** of these for them: 1. Started a care flow 2. Activated an action 3. Triggered a reminder ## A patient can be active without doing anything [#a-patient-can-be-active-without-doing-anything] > **The patient does not need to have done anything themselves.** Sending a reminder marks that patient > as active. A long-running flow that sends monthly reminders to a dormant population keeps that population active, and billable, whether or not anyone responds. If a cohort has genuinely finished, [stop their care flow](/docs/run-care-flows/stop-or-delete-a-care-flow) so those patients stop counting as active. > **Commercial accuracy**: this page describes the billing model as documented. Confirm the current > definition with [support@awellhealth.com](mailto:support@awellhealth.com) before relying on it for > forecasting. ## Next steps [#next-steps] **Next:** [Data catalog](/docs/data/data-catalog) to see what a care flow collects. # Protect care flows URL: https://docs.awellhealth.com/docs/data/protect-care-flows A **protected** care flow can be edited in Awell Studio by anyone, but **publication requires the changes to be merged into the branch Source Control pushes to** through the Source Control provider. ## It separates who can design from who can release [#it-separates-who-can-design-from-who-can-release] Clinical and operations colleagues keep full freedom to build and change care flows. Engineers keep control of when a care flow is ready to go live. The gate matters most when a care flow is tightly integrated with proprietary systems, where publishing can have effects outside Awell. ## It requires Source Control on the care flow [#it-requires-source-control-on-the-care-flow] Protection requires [Source Control](/docs/data/source-control) on the care flow, since the merge is the gate. ## Next steps [#next-steps] **Next:** [Deploy care flows](/docs/data/deploy-care-flows). # Set up Source Control URL: https://docs.awellhealth.com/docs/data/set-up-source-control The setup is the same for both providers apart from creating the access token. Start with a **new, dedicated repository** rather than an existing one: it keeps the sync clean and the history entirely about this care flow. ## Connect the repository, then test before saving [#connect-the-repository-then-test-before-saving] ### 1. Create a new Git repository [#1-create-a-new-git-repository] Create a dedicated repository for Awell's Source Control. ### 2. Enter the repository URL into Awell [#2-enter-the-repository-url-into-awell] Paste the repository URL into the care flow's Source Control settings. ### 3. Set the branch name [#3-set-the-branch-name] Specify the branch Awell should sync to. ### 4. Create an access token [#4-create-an-access-token] See below. ### 5. Copy the generated token into Awell [#5-copy-the-generated-token-into-awell] Paste the token into the token field in Awell. ### 6. Test and save [#6-test-and-save] GitLab offers a **Test Source Control** action. Test the configuration before saving on either provider; otherwise a wrong token isn't discovered until publish time. ## The token is the one step that differs by provider [#the-token-is-the-one-step-that-differs-by-provider] ### GitHub [#github] Create a **fine-grained personal access token** with access to the new repository. Fine-grained tokens can be scoped to a single repository, so use that rather than a classic token with broad access. ### GitLab [#gitlab] Create a **personal access token** with access to the repository. ## After setup, every publish triggers a sync [#after-setup-every-publish-triggers-a-sync] The care flow syncs to the repository each time a new version is published. See [How syncing works](/docs/data/syncing-to-scm) for what that does and doesn't mean. ## Next steps [#next-steps] **Next:** [How syncing works](/docs/data/syncing-to-scm). # Source Control URL: https://docs.awellhealth.com/docs/data/source-control **Source Control** syncs care flows as code to a remote Source Control Management provider such as GitHub. Once it's set up, the care flow syncs to the repository every time a new version is published. ## Care flow changes become reviewable as diffs [#care-flow-changes-become-reviewable-as-diffs] What Source Control makes possible: 1. **Care flows as code.** Care flow components live in a repository the organization owns. 2. **CI/CD integration.** Care flow updates can flow through the pipelines the team already runs. 3. **Code-based testing.** Verify care flow behavior with existing test tooling. 4. **Visibility on changes.** Inspect and diff versions of a care flow as code. Visibility changes how a clinical change gets reviewed: a diff is something a colleague can check; a description of what someone changed in a canvas is not. ## Configure it from the care flow's Settings tab [#configure-it-from-the-care-flows-settings-tab] 1. Select the care flow to put under Source Control. 2. Go to the **Settings** tab and choose **Source Control** to configure the repository. 1. Paste the repository URL into the repository URL field. 2. Paste the access token into the token field. 3. **Test** the configuration to confirm the permissions are right. The Source Control settings on a care flow, with fields for repository URL, branch and access token Three values are needed: the **repository URL**, the **branch** every change is pushed to, and a **personal access token** with `repo`, `contents:read`, `contents:write` and `metadata:read`. **Test configuration** checks the connection before saving. Awell stores the configuration and uses it to create and delete a branch. For the full provider walkthrough, see [Set up Source Control](/docs/data/set-up-source-control). ## Editing the repository does not change the care flow [#editing-the-repository-does-not-change-the-care-flow] The sync is **one-way**, and Source Control is set up per care flow per environment. [How syncing works](/docs/data/syncing-to-scm) has the detail. ## Next steps [#next-steps] **Next:** [Set up Source Control](/docs/data/set-up-source-control). # How syncing works URL: https://docs.awellhealth.com/docs/data/syncing-to-scm The way Source Control syncs limits what it can be used for. Read this page before designing a workflow around it. ## One repository per care flow, per environment [#one-repository-per-care-flow-per-environment] Source Control is set up for **each care flow and each environment individually**, which means a separate repository for every care flow in every environment. So ten care flows across Sandbox and Production is twenty repositories. Plan a naming convention before creating the first one. ## The sync is one-way [#the-sync-is-one-way] > **Source Control is unidirectional.** Changes made in Awell Studio are pushed to the provider; > changes made in the repository are not pushed back. Nothing stops anyone editing the care flow JSON in the repository. Those edits **won't appear in Studio, and they will be overwritten** the next time the care flow is published. A repository that looks editable but discards changes without warning can leave someone believing a clinical change shipped when it didn't. Treat the repository as an output. ## Best for visibility, review and gating, not authoring [#best-for-visibility-review-and-gating-not-authoring] What Source Control does well: * diffing what changed between versions * reviewing a clinical change as a diff * [gating publication](/docs/data/protect-care-flows) behind a merge * [deploying](/docs/data/deploy-care-flows) through a CI/CD pipeline ## Next steps [#next-steps] **Next:** [Protect care flows](/docs/data/protect-care-flows). # Activity model and lifecycle URL: https://docs.awellhealth.com/docs/embed-and-host/activity-model-and-lifecycle An **activity** is a single task a stakeholder completes in a care flow: a form, a checklist, a message to acknowledge, or a custom extension action. Activities are orchestrated by the backend and rendered by the embedded portal. The host app displays activities; the care flow decides which ones exist and what happens next. ## Supported activity types [#supported-activity-types] Navi renders forms, checklists, message acknowledgments, and activities produced by custom extensions. ## Lifecycle: build against events, not polling [#lifecycle-build-against-events-not-polling] An activity moves through states as the stakeholder works on it, from becoming available, through in-progress, to complete. Navi emits an event at each transition, which is how the host app reacts. See [Events emitted by Navi](/docs/embed-and-host) for the full event reference. The care flow can create and expire activities with no input from the stakeholder, so a UI that assumes a fixed list will drift. ## Validation comes from the care flow, not the client [#validation-comes-from-the-care-flow-not-the-client] Validation happens where the activity is defined. A form's rules come from the care flow design, so Navi enforces the same rules everywhere the form appears. There is no validation to reimplement in the client, and no way to override it from there. If a rule is wrong, change it in [Studio](/docs/design-care-flows). ## Next steps [#next-steps] **Next:** [Sessions and JWTs](/docs/embed-and-host/sessions-and-jwts) for how access is granted. # Branding and theming URL: https://docs.awellhealth.com/docs/embed-and-host/branding-and-theming Navi's appearance comes from a branding configuration, set in either of these places: * **Organization-wide in the CareOps portal.** Recommended, because everything stays consistent. * **Per app or per embed**, set through the SDK. Start with the organization-wide setting and override only where a specific surface genuinely needs to differ, because scattered overrides make it hard to tell which one applies. ## Step 1: Configure branding in the CareOps portal [#step-1-configure-branding-in-the-careops-portal] Set the organization's branding once, and every Navi embed picks it up. Hosted Pages has its own settings alongside it, including the page title stakeholders see and the accent color applied to it. Hosted Pages branding settings, with fields for the page title and the accent color ## Step 2: Optional overrides in the embedding app [#step-2-optional-overrides-in-the-embedding-app] Pass a branding configuration through the SDK to override specific values for one app or one embed. ## Fonts have to be loaded by the embedding page [#fonts-have-to-be-loaded-by-the-embedding-page] A font Navi can't reach falls back to a default. ## Checklist [#checklist] * Branding configured at organization level * Any per-app overrides deliberate and documented * Custom fonts loaded by the embedding app * Checked on a phone as well as a desktop ## Troubleshooting: configuration, then overrides, then environment [#troubleshooting-configuration-then-overrides-then-environment] If branding doesn't appear, check the organization configuration, then whether an override is winning, then whether the environment on screen is the one that was configured. Branding is set per environment. See the [go-live checklist](/docs/design-care-flows/go-live-checklist). ## Next steps [#next-steps] Back to [Embed & host](/docs/embed-and-host) for the other options. # Build your own UI URL: https://docs.awellhealth.com/docs/embed-and-host/build-your-own-ui A custom interface on top of the Orchestration API gives full control of every pixel and interaction, and means owning every edge case. Before choosing it, be clear about what the other options already handle: * **[Hosted Pages](/docs/embed-and-host/overview-hosted-pages)** already handles accessibility, internationalization, responsive layout, keyboard navigation and form auto-save, all of which take real work to rebuild well. * **[Navi](/docs/embed-and-host/what-is-navi)** renders activities inside the host product, with the organization's branding, while Awell maintains the activity rendering and its edge cases. Build a custom UI for something genuinely different: an interaction model neither supports, or a surface such as a kiosk or a native component that has to be first-party. ## Everything a UI needs is in the Orchestration API [#everything-a-ui-needs-is-in-the-orchestration-api] The API covers reading pending activities, submitting form responses and completing activities. See [the API reference](/api-reference). The [activity model and lifecycle](/docs/embed-and-host/activity-model-and-lifecycle) is worth reading even without Navi, because it describes the states a custom UI has to handle. ## Next steps [#next-steps] **Next:** [What is Navi?](/docs/embed-and-host/what-is-navi), often the middle ground between a custom UI and Hosted Pages. # Built-in and customizable features URL: https://docs.awellhealth.com/docs/embed-and-host/built-in-and-customizable-features Hosted Pages is built to be simple, accessible and customizable. This page separates what comes as standard from what gets configured. ## Accessibility, languages and auto-save come as standard [#accessibility-languages-and-auto-save-come-as-standard] These need no configuration, which is the main reason to use Hosted Pages instead of a custom UI. * **Accessibility.** Built in rather than retrofitted. * **Internationalization.** Multiple languages supported. * **Simple design.** Deliberately plain, so patients aren't learning an interface while trying to answer a question. * **Optimized for any device.** Works on a phone as well as a desktop. * **Keyboard navigation.** Useful for clinical users working at speed, and for accessibility. * **Form response auto-save.** A patient who loses signal partway through a long form doesn't start again. ## Branding, domain and form display mode are configurable [#branding-domain-and-form-display-mode-are-configurable] * **Branding.** The organization's logo and colors. See [Hosted Pages settings](/docs/embed-and-host/hosted-pages-settings). * **Custom domain.** So the URL belongs to the care organization. See [Set a custom domain](/docs/embed-and-host/set-a-custom-domain-for-hosted-pages). * **Form display mode.** One question at a time, or all at once. See [Set a display mode for your forms](/docs/design-care-flows/set-a-display-mode-for-your-forms). ## Next steps [#next-steps] **Next:** [Sessions and links](/docs/embed-and-host/sessions-and-links) to get a URL a patient can open. # Care flow design with Hosted Pages URL: https://docs.awellhealth.com/docs/embed-and-host/care-flow-design-with-hosted-pages A care flow completed on Hosted Pages needs more thought about timing than one completed inside Awell Care, because the patient is **waiting** while it runs. ## System activities make the patient wait [#system-activities-make-the-patient-wait] A care flow contains both stakeholder activities and system activities: * **Stakeholder activities** that a person does: a form, a message, a checklist. * **System activities** that Awell does: a calculation, an API call. On Hosted Pages, a system activity between two stakeholder activities becomes a pause the patient experiences; a call to a slow third-party system shows as a spinner. ## Keep system activities out of the patient's path [#keep-system-activities-out-of-the-patients-path] ### Avoid unnecessary system activities [#avoid-unnecessary-system-activities] A system activity placed between stakeholder activities adds to the time the patient spends waiting. Ask whether each one has to happen *now*. ### Run necessary system activities after or in parallel [#run-necessary-system-activities-after-or-in-parallel] If a system activity must happen, put it **after** the stakeholder has finished, or in parallel with their work, rather than between two of their steps. The patient then finishes their part without waiting for the calculation. ### Send an activity page via a secondary channel [#send-an-activity-page-via-a-secondary-channel] Rather than relying on the patient staying in one session, send a link by email or text message so they can return later. See [Link to an activity from email or SMS](/docs/embed-and-host/link-to-an-activity-from-email-or-sms). ## Next steps [#next-steps] **Next:** [Link to an activity from email or SMS](/docs/embed-and-host/link-to-an-activity-from-email-or-sms). # Hosted Pages settings URL: https://docs.awellhealth.com/docs/embed-and-host/hosted-pages-settings Hosted Pages settings change how it looks and behaves for patients and care teams. They are set for **one care flow** or for **the whole organization**. ## Per care flow [#per-care-flow] The Hosted pages style settings on a care flow, with logo, accent colour, page title, auto progress and answer autosave ### Sharing [#sharing] The Hosted Pages sharing link for this care flow, including the QR code version. See [Trigger with a Hosted Pages link](/docs/automate-with-events/trigger-with-a-hosted-pages-link). A sharing link belongs to one care flow. It is **not** carried over when someone [duplicates a care flow](/docs/design-care-flows/duplicate-a-care-flow). ### Style [#style] Look and feel for this care flow only. Useful when one care flow is for patients and another is for clinicians, and the two don't have to look the same. ## For the whole organization [#for-the-whole-organization] Organization-level settings apply everywhere and are the right default. Set them once, and override per care flow only where there's a reason. Branding is set at organization level. See [Administer & secure](/docs/administer-and-secure). ## Settings are per environment [#settings-are-per-environment] Setting them in Sandbox does **not** set them in Production, so check them in Production before go-live. See the [go-live checklist](/docs/design-care-flows/go-live-checklist). ## Next steps [#next-steps] **Next:** [Set a custom domain](/docs/embed-and-host/set-a-custom-domain-for-hosted-pages) so the URL matches the organization too. # Embed & host URL: https://docs.awellhealth.com/docs/embed-and-host This section covers where patients and clinicians do what a care flow asks of them: fill in a form, read a message, confirm an appointment. ## Placement decides which option fits [#placement-decides-which-option-fits] | Option | Effort | Controls | Best when | | -------------------------------------------------------------- | ------- | -------------------------- | ------------------------------------------------------ | | **[Hosted Pages](/docs/embed-and-host/overview-hosted-pages)** | Lowest | Branding and settings | Going live fast matters, and Awell's UI is good enough | | **[Navi](/docs/embed-and-host/what-is-navi)** | Medium | Placement, theming, events | Activities belong inside an existing product | | **[Your own UI](/docs/embed-and-host/build-your-own-ui)** | Highest | Everything | Neither of the above allows what's needed | Hosted Pages and Navi are both prebuilt UI for care flows, so the difference between them is placement: Hosted Pages is a page a stakeholder is sent to, or an iframe, while Navi is a component rendered **inside** an existing app. Use Navi where patients already use the host product, and Hosted Pages where they are sent a link. ## Hosted Pages [#hosted-pages] * [What Hosted Pages is](/docs/embed-and-host/overview-hosted-pages) * [Built-in and customizable features](/docs/embed-and-host/built-in-and-customizable-features) * [Sessions and links](/docs/embed-and-host/sessions-and-links): how to get a URL for a stakeholder * [Embed or redirect](/docs/embed-and-host/redirect-or-embed) * [Hosted Pages settings](/docs/embed-and-host/hosted-pages-settings) * [Set a custom domain](/docs/embed-and-host/set-a-custom-domain-for-hosted-pages) * [Care flow design with Hosted Pages](/docs/embed-and-host/care-flow-design-with-hosted-pages) * [Link to an activity from email or SMS](/docs/embed-and-host/link-to-an-activity-from-email-or-sms) * [Tracking and attribution](/docs/embed-and-host/tracking) ## Navi [#navi] * [What is Navi?](/docs/embed-and-host/what-is-navi) * [Quickstart](/docs/embed-and-host/quickstart): get something rendering * [Activity model and lifecycle](/docs/embed-and-host/activity-model-and-lifecycle) * [Sessions and JWTs](/docs/embed-and-host/sessions-and-jwts) * [Branding and theming](/docs/embed-and-host/branding-and-theming) ## Authors choose the surface; engineers embed it [#authors-choose-the-surface-engineers-embed-it] Picking an option and branding the result is a care flow author's call; embedding it is an engineer's. # Link to an activity from email or SMS URL: https://docs.awellhealth.com/docs/embed-and-host/link-to-an-activity-from-email-or-sms Use this to reach a stakeholder by email or text message and let them complete a pending activity straight from the message, rather than asking them to log in somewhere. > Not to be confused with [embedding Hosted Pages](/docs/embed-and-host/redirect-or-embed), which puts > Hosted Pages inside a host app rather than a link inside a message. ## Before starting [#before-starting] Activate one of the communication extensions, so the **Send Email** or **Send SMS** actions are available. See [Integrate with extensions](/docs/connect-systems/integrate-with-extensions). ## Add the link [#add-the-link] 1. Double-click the step that sends the email or text message. 2. Add a **Send Email** or **Send SMS** action. 3. Add the activity page link to the dynamic template data for email, or directly into the body of the text message. The “Sent” tab of a Send SMS (with from number) action, in the “Send values to Twilio” section: a “From” number field and a required “To” phone number field, each with a Fixed value / Data point toggle, and below them the message toolbar, where a yellow arrow points at a small blue button whose tooltip reads “Insert Hosted Pages”. The message box beneath holds “Hi firstName, click the link below to continue your intake paperwork.” and an “Activity Page: Patient” link A dynamic email template can render the link as a "click here" button, so it reads as the call to action rather than a URL in the middle of a paragraph. ## Next steps [#next-steps] * [Send email notifications](/docs/design-care-flows/send-email-notifications) for configuring email. * [Care flow design with Hosted Pages](/docs/embed-and-host/care-flow-design-with-hosted-pages) for why a secondary channel is worth having. # Navi architecture and security URL: https://docs.awellhealth.com/docs/embed-and-host/navi-architecture-and-security Navi's security model follows from its architecture, so this is the page to give a security reviewer. ## Navi has a CDN loader, an embedded portal and backend APIs [#navi-has-a-cdn-loader-an-embedded-portal-and-backend-apis] * A **CDN loader** (`navi-loader.js`) initializes the SDK and creates iframes. * An **embedded portal** on a **separate origin** renders activities and handles validation. * **Backend APIs** process submissions and advance care flows. Because the portal runs on a separate origin, a host page can embed it without reaching into it. ## Only three kinds of message cross the iframe boundary [#only-three-kinds-of-message-cross-the-iframe-boundary] The parent page and the iframe communicate through `postMessage`, and messages are **strictly scoped** to: * request and response for data collection * height and width changes * session status and completion Nothing else crosses the boundary, which keeps the surface small enough to reason about. ## An origin allow-list and tokenization keep data out of the parent page [#an-origin-allow-list-and-tokenization-keep-data-out-of-the-parent-page] * **Origin allow-list.** Messages from an unexpected origin are ignored. * **Tokenization.** Sensitive data is never exposed to the parent page; only tokens and results cross origins. * **Publishable keys** are safe to ship in front-end code, unlike secret keys. See [Quickstart](/docs/embed-and-host/quickstart). ## The parent application never handles the clinical data [#the-parent-application-never-handles-the-clinical-data] Keeping the data out of the parent page reduces what the host application is responsible for, which counts in a compliance review: activities render inside the product without that product becoming a processor of the responses. ## Next steps [#next-steps] * [Sessions and JWTs](/docs/embed-and-host/sessions-and-jwts) for how access is granted. * [Administer & secure](/docs/administer-and-secure) for organization-level security. # Awell Hosted Pages URL: https://docs.awellhealth.com/docs/embed-and-host/overview-hosted-pages **Hosted Pages is a prebuilt app** where patients and other stakeholders interact with their pending care flow activities: filling in forms, reading messages, completing checklists. Either send someone a link to it, or embed it in a site. It needs little or no code, which makes it the quickest way to get started with Awell. ## Hosted Pages is the prebuilt checkout page, not the API [#hosted-pages-is-the-prebuilt-checkout-page-not-the-api] Adding payments to an application needs a page where the customer sees the amount and enters card details. Build that page on Stripe's API, or use Stripe's prebuilt checkout page. Hosted Pages plays the same role, and its built-in and [customizable features](/docs/embed-and-host/built-in-and-customizable-features) mean going live without building a UI. ## Get a URL from an Awell-generated link or an API session [#get-a-url-from-an-awell-generated-link-or-an-api-session] 1. **Hosted Pages links** that Awell generates and sends to the integrating system at the right moment. 2. **A session created through the API**, which returns a session URL. Both are covered in [Sessions and links](/docs/embed-and-host/sessions-and-links). Either way, the next choice is [embed or redirect](/docs/embed-and-host/redirect-or-embed). ## Hosted Pages covers pending activities, not the patient record [#hosted-pages-covers-pending-activities-not-the-patient-record] Hosted Pages is not a patient app, and it is not a general-purpose portal. Its only job is letting patients and stakeholders complete pending activities in a care flow, so it is not a place to hold a patient's record or a messaging inbox. A patient app is something the care organization builds, and [Navi](/docs/embed-and-host/what-is-navi) is how Awell activities go inside it. ## Next steps [#next-steps] **Next:** [Built-in and customizable features](/docs/embed-and-host/built-in-and-customizable-features) to see what comes as standard and what can change. # Navi quickstart URL: https://docs.awellhealth.com/docs/embed-and-host/quickstart By the end of this, a real care flow activity renders inside the host app. Navi installs through the **React SDK**, or through a **script tag** for anything that isn't React. ## React [#react] ### 1. Generate a publishable key [#1-generate-a-publishable-key] In the CareOps portal, create a publishable key. It looks like `pk_test-...`. Publishable keys are safe in client code; never put a secret API key in front-end code. ### 2. Install the packages [#2-install-the-packages] Install the Navi SDK packages. ### 3. Wrap the app with the provider [#3-wrap-the-app-with-the-provider] Wrap the application in Navi's provider and pass the publishable key. ### 4. Render the first care flow or activity [#4-render-the-first-care-flow-or-activity] Render Navi's component where the activity should appear. ### 5. Run the app [#5-run-the-app] Start the app and open the page. A live activity appears. ## Script tag [#script-tag] For apps that aren't React: ### 1. Generate a publishable key [#1-generate-a-publishable-key-1] Same as above. ### 2. Add the script and container [#2-add-the-script-and-container] Add Navi's script to the page and a container element for it to render into. ### 3. Initialize and render [#3-initialize-and-render] Initialize Navi with the publishable key and point it at the container. ## Keys are per environment [#keys-are-per-environment] Use a **test** publishable key against Sandbox during build, and swap to a production key at go-live. A key from the wrong environment produces a confusing empty screen. See the [go-live checklist](/docs/design-care-flows/go-live-checklist). ## Next steps [#next-steps] **Next:** [Activity model and lifecycle](/docs/embed-and-host/activity-model-and-lifecycle) to understand what just rendered. # Embed or redirect to Hosted Pages URL: https://docs.awellhealth.com/docs/embed-and-host/redirect-or-embed Once a [Hosted Pages URL](/docs/embed-and-host/sessions-and-links) exists, embed it in the host app or send the stakeholder to it. **Both offer identical features.** Embedding keeps the stakeholder inside the host product. ## Redirect [#redirect] Send the stakeholder to the URL, for example with a link: ```html Complete my activities ``` ## Embed [#embed] Put the URL in an iframe: ```html