Merge pull request #155 from awell-health/awell_studio_docs

Doc update: Awell Studio space added

content/awell-orchestration/docs/getting-started/domain-model.mdx → content/awell-orchestration/api-reference/overview/domain-model.mdx

@@ -3,20 +3,6 @@ title: Domain model
 description: Familiarize yourself with our API domain model
 ---
 
-## Introduction: Awell Orchestration as a "State Machine"
-
-In essence, Awell Orchestration and its corresponding API can be seen as a state machine. For every patient enrolled in a care flow you've designed and published, Awell knows exactly what happened, what inputs are needed next and what activities need to happen by whom and when. You can feed data into the machine (eg: a patient submits a form) to let Awell Orchestration recompute what's next.
-
-<Alert type="info">
-  <p>
-    Note that integrating directly with our API is only one of the ways you can
-    orchestrate care flows in Awell. Check out how to [Interact with
-    activities](/awell-orchestration/docs/activities/overview-activities)
-  </p>
-</Alert>
-
-## High level lifecycle of interacting with a care flow through our API
-
 All of the interactions with Awell Orchestration are accessible through our API. For full detail, see our [API Reference](/awell-orchestration/api-reference/overview/endpoints).
 
 Below is a typical, although very basic, lifecycle of interacting with our API.

content/awell-orchestration/developer-tools/webhooks/introduction.mdx

@@ -34,7 +34,7 @@ You can start receiving event notifications in your app using the steps in this
 2. Create a webhook endpoint as an HTTPS endpoint (URL) that can accept POST requests on your local server.
 3. Handle requests from Awell by parsing each event object and returning 2xx response status codes.
 4. Deploy your webhook endpoint so it’s a publicly accessible HTTPS URL.
-5. Register your publicly accessible HTTPS URL in the Pathway settings of a pathway in [Awell studio](/awell-orchestration/docs/getting-started/awell-ecosystem#awell-studio).
+5. Register your publicly accessible HTTPS URL in the Pathway settings of a pathway in Awell studio.
 
 ## Configure webhooks in pathways
 

content/awell-orchestration/docs/getting-started/orchestration-introduction.mdx

@@ -0,0 +1,98 @@
+---
+title: Introduction
+description: What is Awell Orchestration?
+---
+
+## What is Awell Orchestration?
+
+**Awell Orchestration is the part of Awell's platform that allows you to run your care flows, designed in [Awell Studio](/awell-studio/docs/getting-started/studio-introduction), for your patient population.** It automatically handles the variability encoded in the care flow you designed by evaluating all conditional logic, activating and discarding branches, scheduling activities and assigning them to the right stakeholder and more.
+
+Awell exposes a powerful Orchestration API and low-code solutions allowing you to embed your care flows into your tech stack.
+
+<figure className="w-full flex flex-col justify-center text-center">
+  <div>
+    <a
+      href="https://res.cloudinary.com/da7x4rzl4/image/upload/v1651756063/Developer%20portal/6294e9d29b81f84d698d7514_API.png"
+      target="_blank"
+      className="custom-link"
+    >
+      <img
+        src="https://res.cloudinary.com/da7x4rzl4/image/upload/v1651756063/Developer%20portal/6294e9d29b81f84d698d7514_API.png"
+        alt="Pathway versioning"
+        className="w-full sm:w-9/12 p-4 dark:p-0 mx-auto bg-[#001A44] dark:bg-transparent rounded-lg"
+      />
+    </a>
+  </div>
+  <figcaption className="dark:text-slate-400 pt-1">
+    Orchestrate care flows with Awell's Orchestration API
+  </figcaption>
+</figure>
+
+### From Design to Orchestration
+
+After publishing a care flow in Awell Studio, you will want to start enrolling patients in that flow. From that point onwards, Awell orchestrates all activities for all stakeholders in the care flow in the back-end. To allow users to interact with these activities you can integrate with our Orchestration API for full control over the end-user experience or leverage one of our low-code options to provide user interfaces to your patient and care team members. Orchestration also means automating data flow and integrations with 3d party systems like your EMR.
+
+**Orchestrating care flows is the act of enrolling a patient into the care flow you have designed and published in [Awell Studio](/awell-studio/docs/getting-started/studio-introduction).** The orchestration domain is exposed by an API, the "Orchestration API" and this is the API you'll integrate against.
+
+Whereas in the design domain you've built a theoretical model or blueprint of your care flow, when orchestrating care flows you'll be actually executing a care flow for patient against that model or blueprint.
+
+**The Orchestration domain will therefore help you with answering the following questions:**
+
+- For a given patient in a care flow, what are the current actions to complete?
+- For a given patient in a care flow, what are the upcoming steps that will be activated?
+- For a given patient in a care flow, what are the completed tracks, steps, and actions?
+
+Additionally, you can also let the Orchestration API know that certain pieces of data were collected, actions were completed, etc. Which could be a trigger to go to the next step or activate a new track.
+
+### State machine
+
+In essence, Awell Orchestration and its corresponding API can be seen as a state machine. For every patient enrolled in a care flow you've designed and published, Awell knows exactly what happened, what inputs are needed next and what activities need to happen by whom and when. You can feed data into the machine (eg: a patient submits a form) to let Awell Orchestration recompute what's next.
+
+<Alert type="info">
+  <p>
+    Note that integrating directly with our API is only one of the ways you can
+    orchestrate care flows in Awell. Check out how to{' '}
+    <a
+      href="/awell-orchestration/docs/activities/overview-activities"
+      title="Interact with
+    activities"
+    >
+      interact with activities
+    </a>
+    .
+  </p>
+</Alert>
+
+### Awell Studio vs. Awell Orchestration
+
+<div className="table-wrapper">
+  <table>
+    <thead>
+      <tr>
+        <th align="center">
+          <strong>Awell Studio</strong>
+        </th>
+        <th align="center">
+          <strong>Awell Orchestration</strong>
+        </th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td width="50%" align="center">
+          Design, build, and publish care flows using Awell's low-code editor.
+        </td>
+        <td width="50%" align="center">
+          Orchestrate or run care flows for your patient population with Awell's
+          API and integrate them in your tech stack.
+        </td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+
+## Integrations
+
+We strongly believe in an ecosystem of solutions (vs. a monolithic one-app-to-rule-them-all).
+
+From your EMR or practice management software to your patient app, scheduling and medication delivery, Awell integrates with your existing tech stack. Check our [Webhooks](/awell-orchestration/developer-tools/webhooks/introduction) and [Healthcare interoperability](/awell-orchestration/docs/data/healthcare-interoperability) for more information or contact us to discuss your particular set-up.

content/awell-orchestration/docs/getting-started/orchestration-ontology.mdx

@@ -0,0 +1,55 @@
+---
+title: Orchestration ontology
+description: Learn more about Awell's ontology to orchestrate care flows
+---
+
+## Design ontology
+
+Before diving into the Orchestration ontology, we recommend reading our [Design ontology](/awell-studio/docs/getting-started/design-ontology) to learn more about how care flows are structured when designing them in Awell Studio.
+
+## Orchestration ontology
+
+**When a care flow is orchestrated, it is translated to a set of activities.** So when an [action](/awell-studio/docs/getting-started/design-ontology#actions) is activated, an activity is created in the Awell System to keep track of its start date, status, completion date, etc. The activity stores a reference to the [action](/awell-studio/docs/getting-started/design-ontology#actions), [step](/awell-studio/docs/getting-started/design-ontology#steps-and-transitions), and [track](/awell-studio/docs/getting-started/design-ontology#tracks-and-triggers) so we know at all times what action needs to be completed as part of what activity and in what context the activity is created.
+
+We use the concept of activities because, depending on how your care flow is structured, a track or step (and thus the actions in it) might be activated more than once.
+
+<figure className="w-full flex flex-col justify-center text-center relative">
+  <div className="bg-[#F0F6FF] p-12 w-full mx-auto rounded-md">
+    <a
+      href="https://res.cloudinary.com/da7x4rzl4/image/upload/v1678295646/Developer%20portal/action-activity.png"
+      target="_blank"
+      title="Action vs. Activity"
+    >
+      <img
+        src="https://res.cloudinary.com/da7x4rzl4/image/upload/v1678295646/Developer%20portal/action-activity.png"
+        alt="Action vs. Activity"
+      />
+    </a>
+  </div>
+  <figcaption className="dark:text-slate-400 pt-2">
+    Action vs. Activity
+  </figcaption>
+</figure>
+
+Please note that an orchestrated care flow does not only consist of activities related to actions but that there are many other (system) activities as well (eg: track activation/completion, step activation/completion, reminders, ...). You can thus look at activities as a full history log of what has happened in a pathway.
+
+### Activities and data points
+
+Where tracks and triggers, steps and transitions, and actions were the main building blocks when designing care flows, the main elements you will engage with when Orchestrating care flows are activities and data points.
+
+<div className="grid gap-6 mx-auto grid-cols-2">
+  <div className="grid items-center grid-flow-col p-4 bg-slate-100 rounded-2xl dark:bg-slate-400">
+    <div className="flex justify-center">
+      <div className="text-lg font-bold text-slate-800 text-center my-6 dark:text-slate-100">
+        Activities
+      </div>
+    </div>
+  </div>
+  <div className="grid items-center grid-flow-col p-4 bg-slate-100 rounded-2xl dark:bg-slate-400">
+    <div className="flex justify-center">
+      <div className="text-lg font-bold text-slate-800 text-center my-6 dark:text-slate-100">
+        Data points
+      </div>
+    </div>
+  </div>
+</div>

content/awell-orchestration/docs/getting-started/orchestration-versioning.mdx

@@ -0,0 +1,16 @@
+---
+title: Versioning with Awell Orchestration
+description: Learn more about how versioning works when Orchestrating care flows
+---
+
+**Every time a care flow is published in Awell Studio, a new version is created for that care flow.** Every version represents an immutable snapshot of the state of all the components associated with that care flow at the time of publishing. [Before moving on, we recommend reading more about how versioning works in Awell Studio](/awell-studio/docs/getting-started/versioning).
+
+### Starting a care flow
+
+When you enroll a patient in a care flow, the Orchestrator will enroll the patient in the version of the care flow [that is set as the live version](/awell-studio/docs/getting-started/versioning#set-the-live-version).
+
+### Migrate patients from one version to another
+
+It might be that you've included a patient in version 1 of your care flow but you're ready to publish version 2 and you're wondering whether you can "upgrade" the patients enrolled in previous versions to the latest version.
+
+Unfortunately, that's not possible yet but we're working on improved support with the ability to upgrade started care flows/pathways to a newer version.