Automating care recommendations with Workflows

Workflows can be used to generate recommendations for your Patients, such as specific Care Plans or Products, based on their responses to questionnaire Submissions and Patient data.

Workflow Basics

  • Recommendations are generated by conditions and can be generated either before or after a user registers as a Patient in Capable Health.
  • We recommend that a Workflow be created in the Capable admin portal.
  • Each Workflow must have a name and a description.
  • A Workflow can consist of one or more conditions and one or more recommendations.
  • In the Capable Health platform, you can create both chained and branching Workflows.


Capable recommendation

We strongly encourage you to use branching Workflows vs multiple Workflows for the best patient experience.

Creating Conditions

Recommendations can be generated by a Workflow in one of two ways:

1.) by ALL of the conditions being met

2.) by ANY of the conditions being met.

A condition must have a name and the following components:

  • Type: The type must be one of the three options: Patient, Question and Answer.
    • 🧑🏻 Patient: Signifies that the condition is based on a Patient characteristic, such as age or gender, or a tag present on a Patient.
    • ❓ Question: Signifies that the condition is based on a Patient's response to a specific question in a survey Submission. Choose this option if the condition should be triggered by multiple answers to a single question or for a text box question.
      • Multiple answers: Take the question “How often do you have anxiety attacks?” If a condition should be triggered by answers of both “Frequently” and “Sometimes”, choose “Question” as the type and then select the question “How often do you have anxiety attacks?” as the field.
      • Text box: If the question is “What’s your favorite workout activity?” and the condition should be triggered by the answer “running” (entered by the Patient via a text box), choose “Question” as the type and select the question “What’s your favorite workout activity?” Additionally, “running” would be added as the value.
    • ✅ Answer: Signifies that the condition is based on a specific answer to a question in a Patient Submission. For example, with a question such as “Do you have seasonal allergies?”, if a condition should be triggered specifically by a response of “Yes”, choose “Answer” as the type and “Yes” as the value. (See below for more details about the value component.)
  • Field: The Patient characteristic, survey question, or survey answer choice that should trigger the condition. If the type is “Question”, an example could be “How many days postpartum are you?” If the type is “Patient”, an example could be “Age”.
  • Operator: The comparison operator on which the condition should be based, which must be one of the options below. Options are adjusted automatically in the Capable Health platform based on the type selected. Each type allows only a subset of these operators — when you create a Workflow in the Capable admin portal, only the available operators for a given type will appear after you choose the type.
    • equals (==): The equals (==) operator is primarily used for type “Answer”. Example: If you have a single-select question of “Do you sleep more than eight hours a night?” and you want to match the answer “Yes”, you would choose type “Answer”, the equals (==)operator, and a value of “(Do you sleep more than eight hours a night?) Yes”.
    • does not equal (!=)
    • is less than (<)
    • is less than or equal to (<=)
    • is greater than (>)
    • is greater than or equal to (>=)
    • includes: The main use cases for the includes operator are: 1) For tags on the Patient; and 2) for questions with free-text responses. In the case of tags, you can use includes to check whether a Patient has a particular tag.
      • For example, let’s say you want a condition that checks whether a Patient has a tag of lactose intolerant — you would choose type “Patient”, the field “Tags”, the includes operator, and a value of lactose intolerant.
    • doesn't include
    • matches (=~) (recommended for advanced use cases only): The matches (=~) operator generates a case-insensitive regular expression matcher. The matches (=~) operator can only be used with type “Question” and “Patient”. Here are two potential use cases:
      • Matching multiple answers to a single question using one condition: For example, if the type for your condition is “Question” and the field is “How often do you experience anxiety attacks?”, you could use the matches (=~) operator with a value of (frequently|sometimes) to match answers of either frequently or sometimes.
      • Matching a number in a range using one condition: For example, if the type for your condition is “Patient” and the field is “Age”, you could use matches (=~) with a value of [18-30] to match any Patient whose age is in the range of 18-30.
  • Value: The value upon which the condition should be based. For example, if the condition should be triggered when a Patient is under 30 years old, the operator should be is less than (<) and the value should be 30.

Building Workflows: Chained vs Branching

After adding your first condition in our Workflow builder, you have three options to continue building out the workflow.

1.) Add another condition (chained). Depending on your logic and intended output for your workflow, you may want to add more conditions to ensure your patient is guided towards the appropriate recommendation.

2.) Add a split (branching). For more complex Workflows, you may add a split condition.

  • For example, you may at a split to the question “Does your family history include heart disease?”
    • If “Yes”: Workflow branches to the left to recommend a heart health plan.
    • If “No”: Workflow branches to the right to recommend a different Task.

3.) Add a subsequent object (Product, Care Plan, Task or Goal) as a recommendation for a user. You can recommend care objects as a result of the workflow.


A recommendation can be one of four Capable Health entities: A Care PlanGoalTask, or [Product).

Here are a few examples of recommendations a Workflow could generate for Patients:

  • 🧑🏽‍🍼 A Care Plan for postpartum health based on survey answers about a Patient's pregnancy and birth process
  • 🌻 One or more allergy medications (Products) based on survey answers about a Patient's allergy symptoms
  • 😴 A Goal to get a certain amount of sleep each night as part of a sleep-improvement Care Plan

Each recommendation also has a weight, which can be any number. The logic for interpreting the weight of each recommendation should reside in your application, rather than in Capable Health. Here are some possible uses for weight:

  • You may want to give an action a greater or lesser weight depending on certain conditions. For example, if a certain Task is highly recommended when a Patient is over a specific age, you could make the weight of the recommended Task higher for Patients over the cutoff age.
  • Weight can also be negative — a negative weight may be appropriate for actions that are specifically not recommended. For instance, you may want to recommend against a certain Care Plan or Product based on a Patient's medical history or allergy information.

Retrieving recommendations generated from Workflows

You can retrieve recommended actions from Workflows by calling the /workflows/care_suggestions endpoint. You must provide at least one of two possible parameters when calling this endpoint: A submission_id retrieved from a Patient Submission or a patient_id.

If you call the endpoint with a submission_id, your Workflows will act on responses to that Submission AND any available Patient characteristics if the Submission is linked to a Patient. We generally recommend using a submission_id to generate recommendations with Workflows.

If instead, you call the endpoint with a patient_id, your Workflows will act on responses to all the Patient's Submissions in Capable Health in addition to the Patient's demographic data.

Please keep in mind: When you call the /workflows/care_suggestions endpoint, by default you will receive recommendations from all your Workflows that are set as active. Each Workflow has an active status, and if a given workflow’s active status is set to false, that Workflow will not generate its recommendations when calling the endpoint. If you would like to see care suggestions for specific Workflows, you can indicate workflow_idsyou want to run on the given Submission or Patient via the API, as well.

You can also view Workflow recommendations related to a Submission in the Portal by opening a Submission from the Submissions table or a patient’s profile. You’ll be taken to the submission’s detailed view with Patient responses. From here, tap the blue “See Recommendations” button to view the recommendations generated by the workflow.

Committing recommendations for a Patient

If a Patient is recommended a specific Care PlanGoal, or Task, you can “commit” the recommendation to the Patient programmatically. Alternatively, you can have practitioners manually review and approve recommendations in the Capable admin portal before they are assigned to a Patient. You may want to go this route if you want to make sure a knowledgeable human reviews — and potentially amends — care recommendations first.


If you want to commit them programmatically, a Care PlanGoal or Task recommendation object will come with the relevant template ID, i.e., care_plan_template_idgoal_template_id, or task_template_id. This ID will correspond to the relevant Care Plan TemplateGoal Template, or Task Template in your Capable Health system. You can pair that template ID with the relevant Patient ID, then call the appropriate endpoint to create a Care PlanGoal, or Task for the Patient. Note that a recommended Task or Goal must be associated with an existing or new Care Plan to be committed to a Patient.

If a Patient is recommended Products, you can determine the application logic to use, such as displaying the Products to the user or automatically placing them in their cart or adding these Products when creating a Patient Case.