Automating care recommendations with workflows

Workflows can be used to generate recommendations for your users, such as specific Care Plans or Products, based on their responses to questionnaire Submissions and user data. These recommendations 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.

Conditions

Recommendations can be generated by a workflow in one of two ways: 1) by ALL of the conditions being met; or 2) by ANY of the conditions being met. Please keep this in mind when building your workflow logic.

A condition must have a name and the following components:

  • Type: The type must be one of the three options below:
    • 🧑🏻 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. For instance, 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. (See below for more details about the field component.)
    • 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. 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.

Recommendations

A recommendation can be one of four Capable Health entities: A Care Plan, Goal, Task, 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 the conditions that trigger it. 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.

Generating recommendations 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, 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.

Committing recommendations for a Patient

If a Patient is recommended a specific Care Plan, Goal, 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 Plan, Goal or Task recommendation object will come with the relevant template ID, i.e., care_plan_template_id, goal_template_id, or task_template_id. This ID will correspond to the relevant Care Plan Template, Goal 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 Plan, Goal, 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.


Did this page help you?