Workflows

Workflows are automations that run inside your Medipal instance when something happens: a questionnaire is submitted, a patient is created, a questionnaire is published. You design them visually as a graph of steps, test them with sample events, and monitor every run.

What workflows enable

Goal	How a workflow does it
Alert a clinician when a score crosses a threshold	Trigger on Questionnaire Submitted, compute the score, branch on it, send an email through the email plugin.
Push results into another system	Trigger on submission, map the answers into the target's format, call its REST API with an HTTP step.
Remind a patient after a delay	Trigger on enrollment or submission, wait, then send a message.
Keep an external register in sync	Trigger on patient or questionnaire events and call the register's API.
Combine questionnaire scores with clinical values	Read the patient's latest observations from the connected EHR before deciding what to do.

Workflows run on the server, so they continue to work when nobody is signed in.

Building blocks

• Trigger (event subscription). Every workflow listens to one event type. Optional filters narrow it to one questionnaire, folder or user, and an advanced condition can inspect any field of the event.
• Nodes. The steps. Each node has a type, a configuration and, where relevant, an input mapping that says which values from earlier steps it receives.
• Execution connections. Arrows between nodes that define the order. A connection can carry a condition; the next node runs only when the condition is true.
• Data connections. Links that hand one node's output to another node's input, drawn from the output pins to the input pins of a step.
• Runs. Each time the trigger fires, a run is created with a status per node, its inputs, outputs, errors and timings.

Events you can trigger on

Family	Events
Questionnaires	Created, Updated, Published, Archived, Restored, Deleted
Submissions	Questionnaire Submitted, Anonymous Submission, Submission Updated, Submission Deleted
Users	User Created, User Updated, User Deleted, Password Changed
Folders	Folder Created, Folder Updated, Folder Deleted
Sign-in	Login Succeeded, Login Failed, Token Refreshed, Password Reset Requested/Completed, MFA Enabled, MFA Challenge Failed

Submission events carry the answers and the questionnaire structure, so conditions can refer to specific questions and scoring variables.

Node types

Node	What it does
Action	Calls an action of a plugin instance: send an email, call an API described by an OpenAPI document, read platform data.
Compute	Evaluates an expression and stores the result for later steps (a score, a flag, a formatted string).
Switch	Branches. Each outgoing connection has its own condition; the first branch whose condition is true is taken.
Join	Waits for several branches. Modes: all branches, any branch, or a given number of branches.
Delay	Pauses for a duration or until a computed time before continuing.
HTTP	Sends an HTTP request. Method, URL, headers, query and body can all use values from earlier steps.
Mapper	Builds a new object from fields of earlier steps, ready to feed an Action or HTTP node.
End	Marks the end of a path.

Every node also has advanced settings: a timeout, a retry policy (number of attempts and back-off), and continue on error, which lets the run proceed even if this step fails.

Conditions and expressions

Conditions on triggers, connections and Compute nodes are written in JSON Logic, a small, safe expression language. The editor provides a visual tree editor and pickers for event fields, questionnaire questions and variables, and the outputs of earlier nodes, so you rarely type an expression by hand. A condition that checks a scoring variable looks like this:

{ ">=": [{ "var": "event.data.variables.phq9_total" }, 20] }

Comparison, boolean, arithmetic, string, array and date operators are available.

Working with data between steps

• Use data connections to pass a node's output to another node's input. The editor shows what each node exposes: for an HTTP node the status code, headers and body; for an Action the fields declared by the plugin.
• Use a Mapper when the target expects a different shape than what you have, for instance to build the request body for an external API.
• Reference vault entries in mappings and configurations with $secret:name or $var:name. They are resolved on the server at execution time and never appear in run history. See Vault.

Creating a workflow

1. Open Admin Panel → Workflows and choose Create Workflow.
2. Give it a name and pick the event type. Optionally restrict it to a questionnaire, folder or user, or add an advanced condition.
3. Open the editor. Add nodes from the palette, connect them, and configure each node in the side panel.
4. Save, then Test: provide a sample event (the editor pre-fills the shape for the chosen event type) and review which nodes ran, which branches were taken and what each step produced. Tests never call plugins, send requests or wait on delays.
5. Enable the workflow. Disabled workflows keep their definition but ignore events.

Monitoring runs

Admin Panel → Workflows → Runs lists every execution with its workflow, event type, start and end time, and status:

Status	Meaning
Pending	Created, not started yet.
Running	One or more nodes are executing.
Completed	All nodes resolved.
Failed	A node failed and continue on error was off.

A run's detail page shows each node with its own status (pending, running, completed, failed or skipped), its input, output, error and duration. Skipped means the node was on a branch that was not taken.

Related delivery activity is visible under Admin Panel → Events, which lists how each event was handed to workflows and webhooks, with attempts and retry times.

Recipes

Email on a high score. Trigger: Questionnaire Submitted, filtered to the questionnaire. Switch on the total-score variable. On the high branch, an Action node using the email plugin instance with the clinician's address, subject and a body built from the patient's name and score. End.

Forward to an external API. Trigger: Questionnaire Submitted. Mapper builds the payload the external system expects. HTTP node posts it, with the API key taken from $secret:partner_api_key. Switch on the response status code to log or retry.

Delayed reminder. Trigger: Questionnaire Submitted. Delay of a fixed duration. Action node sends the reminder through the email plugin.

Permissions

Viewing workflows and runs requires workflow read rights; creating and editing require workflow write rights, which are not part of the standard clinician role. See Users, Roles & Scopes.

Troubleshooting

Symptom	Likely cause	What to do
The workflow never runs	It is disabled, or the trigger filters do not match the event	Enable it; test with a real event copied from the Events page.
A node fails with a validation error	The input mapping does not match what the action expects	Open the node, compare with the action's input fields, use a Mapper.
The run stops after a Switch	No branch condition was true	Add a default branch with no condition.
Secrets show as $secret:... in the run	Expected: references are resolved only at execution and never logged	No action.
HTTP node times out	Slow or unreachable target	Raise the timeout, add a retry policy, check the target from the Events page.
The test passes but the real run fails	Tests skip plugin calls and requests	Check plugin instance configuration and credentials; see Plugins.