Automation JSON

This page covers the JSON columns behind automations, tasks and the trainee board filters.

`TaskAutomation.flow`

The node flow the automation builder edits. Validated by flowBody in apps/core-api/src/modules/task-automations/flow.schema.ts.

{
  "schemaVersion": 1,
  "trigger": { "time": 3, "unit": "days", "pct": 20, "score": 3, "programs": [], "formTypes": ["CHECK_IN"], "formIds": [] },
  "steps": [
    { "id": "n1", "kind": "task", "assign": "coach", "members": [], "name": "Call the trainee" },
    { "id": "n2", "kind": "wait", "time": 2, "unit": "days" },
    {
      "id": "n3",
      "kind": "paths",
      "branches": [
        {
          "id": "b1",
          "label": "Still inactive",
          "fallback": false,
          "rule": { "field": "daysSinceLogin", "op": "gt", "value": "5", "fieldName": "" },
          "steps": [{ "id": "n4", "kind": "push", "msg": "We miss you" }]
        },
        { "id": "b2", "label": "Otherwise", "fallback": true, "rule": { "field": "program", "op": "eq", "value": "", "fieldName": "" }, "steps": [] }
      ]
    }
  ]
}

Limits

Constant	Value	Meaning
`FLOW_SCHEMA_VERSION`	1	The only accepted `schemaVersion`.
`MAX_FLOW_NODES`	60	Total nodes, counting those inside branches (`countFlowNodes`).
`MAX_BRANCHES_PER_CONDITION`	6	Plus one fallback branch, so a `paths` node holds 2 to 7 branches.
`MAX_CONDITION_DEPTH`	5	Nesting depth of `paths` nodes.

validateFlow runs as a superRefine on save: size, depth, unique node ids, and one trailing fallback per condition. A bad canvas state is refused, never stored.

`trigger`

Key	Type	Default	Meaning
`time`	integer, 0 to 10000	0	The trigger’s threshold or delay.
`unit`	`minutes`, `hours`, `days`	`days`
`pct`	integer, 1 to 500	20	Percentage threshold for the calorie triggers.
`score`	integer, 2 to 10	3	Score threshold for `FORM_RATING_BELOW`.
`programs`	string array, up to 100	`[]`	Limit to trainees on these plans.
`formTypes`	array of `INTAKE`, `CHECK_IN`, `ONE_TIME`, `PDF_SIGNATURE`	absent	Form triggers: which form types. Absent means all four (`flowFormScope`).
`formIds`	string array, up to 500	absent	Narrow to specific forms.

Node kinds

Every node has an id (up to 40 characters) and a kind.

`kind`	Other keys	What it does
`task`	`assign`, `members`, `name`	Creates a Work Board task.
`push`	`msg` (up to 1000)	Sends a push notification to the trainee.
`wa`	`mode`, `source`, `template`, `studioTemplate`, `studioParams`, `msg`, `openChat`	Sends a WhatsApp message.
`webhook`	`label`, `url`	POSTs the event to an external URL.
`content`	`contentId`	Reveals a restricted content item to the trainee. Writes a `ContentItemUnlock` with `source: 'automation'`.
`wait`	`time` (1 to 10000), `unit`	Parks the run.
`paths`	`branches`	Branches on a rule.

`task`

assign is one of none, coach, specific, manager, all. FLOW_ASSIGN_TO_MODE maps it to a TaskAssigneeMode:

`assign`	Mode
`none`	`UNASSIGNED`
`coach`	`RESPONSIBLE`
`specific`	`SPECIFIC`, using `members` (up to 20 coach ids)
`manager`	`OWNER`
`all`	`SPECIFIC` with no ids, which is visible to the whole team

`wa`

Key	Type	Meaning
`mode`	`template` or `free`	An approved template, or free text in `msg`.
`source`	`perform` or `studio`	Where the template lives: Perform’s built-in catalog, or the studio’s own SmartSend account.
`template`	string or null	Id of a Perform catalog template.
`studioTemplate`	string or null	Name of a template in the studio’s SmartSend account.
`studioParams`	array of `{ name, value }`, up to 20	Values per template parameter, in the order SmartSend’s params RPC returns them.
`msg`	string, up to 1000	Free text.
`openChat`	boolean, default `true`

`webhook`

url must be https on a public host. The check refuses localhost, loopback, private ranges, link-local addresses, bracketed IPv6 literals, and .local and .internal names. An empty URL is allowed, so an unconfigured node can be saved, but it cannot run. The payload is described in Outbound webhooks.

`paths`

Each branch has id, label, fallback, rule and steps. The rule:

Key	Type	Meaning
`field`	`program`, `coach`, `formStatus`, `daysSinceLogin`, `formField`, `loggedSince`, `trainee`	What to test.
`op`	`gt`, `lt`, `eq`
`value`	string, up to 200
`fieldName`	string	Only for `field: 'formField'`: which form answer to compare.
`filter`	object	Only for `field: 'trainee'`: one rule of the trainee board’s advanced filter, evaluated by the same engine.

Legacy conversion

When flow is null the automation was never opened in the builder. Readers build an equivalent flow from the TaskAutomationTask rows, so no coach loses a configured name, assignee or delay.

`AutomationFlowRun.position`

The executor’s work stack: an array of frames. A new run starts with one frame at the root:

[{ "loc": [], "index": 0 }]

loc is the chain of branch ids from the root down to the step list this frame walks. An empty array means the flow’s own top-level steps. index is the next node to run in that list. Branch ids are unique within a flow, so a coach reordering nodes cannot point a resumed run at a different branch. A frame is resolved against the automation’s current flow (stepsAt). If the coach deleted that branch while the run was waiting, the frame resolves to nothing. A malformed position restarts from the top, which is safe because the FlowNodeExecution ledger skips nodes that already ran. The run is DONE when the stack is empty. When a node throws, the run becomes FAILED with the position preserved.

`AutomationFlowRun.context`

Facts frozen when the trigger fired, written in flow-runtime.ts:

{
  "triggeredAt": "2026-10-07T06:00:00.000Z",
  "flow": { "schemaVersion": 1, "trigger": {}, "steps": [] },
  "metadata": { "formResponseId": "RESPONSE_ID", "formTemplateId": "FORM_ID", "formName": "Weekly check-in" },
  "clientName": "TRAINEE_NAME",
  "clientFirstName": "TRAINEE_FIRST_NAME",
  "note": "optional note set when the run ends early"
}

Key	Meaning
`triggeredAt`	ISO timestamp. Falls back to the run’s `createdAt` when missing.
`flow`	A copy of the flow as it was when the run started. It is a fallback only. A resumed run reads the automation’s current `flow` first and uses this snapshot when the automation no longer has a valid one.
`metadata`	String map from the trigger, the same one written to the task.
`clientName`, `clientFirstName`	For message placeholders.
`note`	Present on some finished runs.

`TaskAutomation.thresholdByFrequency`

Only for the NO_WORKOUT trigger. Days without a logged workout before a task is created, per weekly-frequency band:

{ "3": 5, "4": 4, "5": 3, "6": 3, "7": 2 }

Keys are WORKOUT_FREQUENCY_BANDS: 3, 4, 5, 6, 7. The value shown is DEFAULT_NO_WORKOUT_DAYS. Each value is clamped to 1 through 60. bandForWorkoutsPerWeek maps a trainee’s meta.workoutsPerWeek to a band: 3 or fewer is band 3, 7 or more is band 7. normalizeFrequencyThresholds fills missing or invalid bands from the defaults.

`InboxItem.metadata`

A small string map. What it holds depends on the task type:

Task about	Keys
A form	`formResponseId`, `formTemplateId`, and `formName` when known (`formTaskMetadata`)
A technique video	`videoId`
A trainee and a plan	`programId`, when relevant

Treat it as optional context. videoIdOf shows the defensive read pattern: check that the value is an object, then that the key is a non-empty string.

`SavedTraineeFilter.rules` and `TraineeFilterState.state`

Both store the trainee board’s advanced filter rules. The API stores rules as an array of free-form objects (up to 50 in a saved state), so an older client’s rule shape still saves. When rules are applied to the clients query they are parsed with filterRule in apps/core-api/src/modules/clients/clients.schema.ts:

{ "field": "daysToEnd", "operator": "between", "min": "0", "max": "14" }

Key	Type	Meaning
`field`	`status`, `coach`, `age`, `formSubmitted`, `lastActivity`, `platform`, `nutritionPlan`, `workoutPlan`, `subscriptionPlan`, `subscriptionStart`, `subscriptionEnd`, `gender`, `tags`, `weight`, `goalWeight`, `joinDate`, `daysToEnd`, `frozen`
`operator`	string	Depends on the field.
`value`	string	Single value.
`values`	string array	Multi-select. The sentinel `__none__` in a plan filter means “no plan”.
`min`, `max`	string	Range bounds. For the subscription date fields a `between` operator reuses them as dates.
`n`	string	A count, for relative operators.
`unit`	`days`, `weeks`, `months`	Unit for `n`.

TraineeFilterState.state is the whole filter bar, validated by traineeFilterStateBody:

{
  "rules": [],
  "lifecycle": "all",
  "health": null,
  "stage": null,
  "activity": null
}

Key	Values
`lifecycle`	`all`, `active`, `inactive`, `inactiveWithAccess`
`health`	`onTrack`, `undocumented` or null
`stage`	`start`, `middle`, `ending`, `ended`, `expired` or null
`activity`	`today`, `week`, `none` or null

The value above is EMPTY_TRAINEE_FILTER_STATE. Both tables are per staff member: userId is the auth user id, and TraineeFilterState is unique on (studioId, userId).

Columns with no fixed shape

Column	Notes
`AutomationRule.trigger`, `AutomationRule.action`	Any object. See Automation and tasks.
`FlowNodeExecution.result`	Whatever the node returned. Informational.
`AuditLog.diff`	The change recorded by the audit entry.
`ClientActivity.metadata`, `LeadActivity.metadata`	Per-activity context.
`AdminDeletion.preview`, `AdminDeletion.result`	The purge preview and its progress counters.
`AutofitImport.counters`, `AutofitImport.report`, `AutofitExerciseMatch.candidates`	See AutoFit import.

​TaskAutomation.flow

​Limits

​trigger

​Node kinds

​task

​wa

​webhook

​paths

​Legacy conversion

​AutomationFlowRun.position

​AutomationFlowRun.context

​TaskAutomation.thresholdByFrequency

​InboxItem.metadata

​SavedTraineeFilter.rules and TraineeFilterState.state

​Columns with no fixed shape