New Submission

trigger.kobotoolbox_event

TriggerBusiness appsconnection requiredruns in-engine

Registers a REST Service on one KoBo form at publish and starts one run per submission. Emits {submission_id, submission_uuid, submitted_at, payload}.

Start a run when a KoboToolbox form receives a new submission.

Ask about KoboToolbox All KoboToolbox nodes Provider API docs ↗

Connection

Required: Yes — the node will not save without one
Auth type: API key
Providers: KoboToolbox
Secret shape: the KoboToolbox API token
Config it needs: base_url
Resolved by: config.connection_id, else node.connection_id
Note: The token needs edit rights on the form — a token that can read submissions can still fail to create a REST Service. Publishing also needs MANTLE_APP_PUBLIC_BASE_URL set to an https URL the KoBo server can reach; KoBo refuses an http endpoint and blocks private addresses.

Configuration

3 fields, 1 required. A dotted path is a nested object and name[] an array of objects — the editor renders the same tree.

Field	Type	Required	Default	Constraints	Example
asset_uid The form (asset) to watch, as the bare uid out of its URL. It must be a literal — the REST Service is created at publish, before any run exists, so an expression cannot be resolved here.	string	Yes	—	matches ^[A-Za-z0-9_-]+$	aSAvYreNzVEkrWg5Gdcvg
subset_fields Send only these question names instead of the whole submission. Leave empty for everything. KoBo's own _id and _uuid are always added back, because a submission without them cannot be de-duplicated.	array	No	—	1–200 characters; array of string	—
email_notification Let KoBo email the form's owner a failure report when a delivery does not succeed. KoBo's own default is on; it is off here so a workflow being republished does not mail somebody who did not ask.	boolean	No	false	—	—

Example configuration

Every value below is the contract’s own example or default — nothing invented.

{
  "asset_uid": "aSAvYreNzVEkrWg5Gdcvg",
  "email_notification": false
}

Output

One shape.

kobotoolbox submission

The flattened submission. `payload` carries the form's own question names, so the shape is open below the declared fields.

Extra keys beyond the ones listed can appear.

Field	Type	Example
submission_id KoBo's numeric submission id (``_id``), as a string so a large id survives anything downstream that would treat it as a JS number. This is the id the kobotoolbox.get_submission node takes.	string	512
submission_uuid KoBo's ``_uuid`` for the submission, and the idempotency key: every one of KoBo's three retries carries the same value, so a retry joins the run it already started instead of starting a second.	string	e3b0c442-98fc-1c14-9afb-f4c8996fb924
instance_id The ODK instance id the collecting device generated (``meta/instanceID``), for matching against a device's own records. Empty when the submission carried none.	string	uuid:e3b0c442-98fc-1c14-9afb-f4c8996fb924
form_id_string The deployed form's id string (``_xform_id_string``) — which form this submission belongs to.	string	aSAvYreNzVEkrWg5Gdcvg
submitted_at When KoBo recorded the submission (``_submission_time``), in the server's own format. Not the time this workflow received it.	string	2024-05-30T12:00:00
submitted_by The KoBo username that submitted, or empty for an anonymous submission.	string	field_officer
attachments The submission's media (``_attachments``) — photos, audio, signatures — each with KoBo's own download_url. Empty when the form collects none.	array	—
hook_uid The uid of the REST Service that delivered this, read off KoBo's User-Agent. Useful when hunting a delivery in the form's REST Services log; it authenticates nothing.	string	hQ4pYt7vXkLmN2rS6wZ1aB
payload The submission exactly as KoBo sent it. The answers are the form's own question names, which is why this shape is open — read them from here.	object	—

{
  "attachments": [],
  "form_id_string": "aSAvYreNzVEkrWg5Gdcvg",
  "hook_uid": "hQ4pYt7vXkLmN2rS6wZ1aB",
  "instance_id": "uuid:e3b0c442-98fc-1c14-9afb-f4c8996fb924",
  "payload": {
    "_id": 512,
    "_submission_time": "2024-05-30T12:00:00",
    "_submitted_by": "field_officer",
    "_uuid": "e3b0c442-98fc-1c14-9afb-f4c8996fb924",
    "_xform_id_string": "aSAvYreNzVEkrWg5Gdcvg",
    "household_name": "Okonkwo",
    "people_in_household": 5
  },
  "submission_id": "512",
  "submission_uuid": "e3b0c442-98fc-1c14-9afb-f4c8996fb924",
  "submitted_at": "2024-05-30T12:00:00",
  "submitted_by": "field_officer"
}

Notes

A REST Service fires on a NEW submission only. Editing existing data does not re-send it, so this trigger cannot see edits.
Publishing creates the REST Service on the form; unpublishing, disabling or archiving deletes it. A workflow that is off is off at KoBo too.
KoBo signs nothing. Each delivery is authenticated by a token this trigger registers as a custom header — that proves the sender, not the bytes.
One run per submission, idempotent on _uuid: KoBo retries a failed delivery after 60 s, 600 s and 6,000 s and a retry cannot start a second run.

Related KoboToolbox nodes

See New Submission run in a workflow.

In a technical demo we add the KoboToolbox connection, drop the node on the canvas and let Workflow Health pre-flight it before the first real run.

Book a technical demo Talk to sales