Domain model

Every interaction with Awell Orchestration goes through the API. This page is the mental model the rest of the reference assumes. Read it before the activity queries, which are hard to use without it.

A typical lifecycle

1. Create a patient. Nothing else can happen first, because every care flow belongs to a patient. See Patients.
2. Start a care flow for that patient. See Start a care flow.
3. Get the pending activities for that care flow. See Query activities.
4. Request the details of the next activity, for example a form's questions.
5. Complete the activity, for example by submitting a form response. See Work with forms.

Then repeat from step 3: an integration is a loop over activities rather than a linear script.

Definitions and instances

The API separates designs from instances:

• A care flow definition is the template designed in Studio.
• A care flow is one patient's instance of it.
• A data point definition is a field in the design; a data point is one patient's value.

Query definitions to ask about your design; query care flows and data points to ask about patients. See Versions and releases for why a definition's version matters.

Activities are the unit of work

An activity is one thing to be done or that happened. Activities cover more than user tasks: track activations, step completions and reminders are activities too, so the activity list is the full history of a care flow rather than a to-do list.

Consequences for an integration:

• Expect system activities you didn't ask for, and filter rather than assuming everything is a task.
• Expect repetition. A looping track produces the same step's activity many times for one patient.

Why GraphQL

Awell chose GraphQL as the primary programmatic interface:

• You query only what you need, which keeps responses small.
• Types and schemas mean client libraries can consume the API without manual parsing.
• Client independence: you can change what you request without waiting for a new endpoint.

Next steps

Next: Start a care flow.