Notion

Run agent work straight off the Notion board your team already keeps. Connect your Notion workspace, share a board with the connection and link it to a Kadmo workspace: assigning the agent to a card starts a run, and the card collects status moves and one comment per step as the run advances.

Before you start

You need	Why
A Notion workspace you own	Creating an internal integration is a workspace-owner action in Notion
A database (board) to work from	Ideally with a Status property — see The workflow column
The Admin role in Kadmo	Saving the connection, testing it and linking a workspace are admin actions

Step 1: Create the internal integration

1. In Notion, open notion.so/profile/integrations and create an internal integration in the workspace you want to automate. Give it a name your team will recognise — the agent's comments and assignments appear under it.
2. Under Capabilities, turn on all of these:

Capability	What Kadmo uses it for
Read content	Read cards, the board's schema and its status options
Update content	Move a card's status, set the assignee, record verdicts
Insert content	Create cards
Read comments	Read the verdict a step posted
Insert comments	Post each step's report on the page
User information	Resolve people and recognise the agent's own edits

3. Copy the integration's secret. It starts with ntn_.

The comment and user switches are off by default

A new Notion integration starts with both comment capabilities and user information switched off. Nothing looks wrong at first — the connection saves and Test Connection passes, because neither touches a comment — but the first run cannot post its report or read its verdict. Turn them on before you leave the Capabilities screen.

Step 2: Share each board with the connection

Notion grants access per database, never per workspace. Owning the workspace grants the integration nothing until someone connects a database to it.

1. Open the database in Notion.
2. Click ••• (top right) → Connections → add your integration.
3. Repeat for every board Kadmo should see — and for every database a relation column points at.

When the database a relation points at is not shared, Notion leaves that property out entirely, so a Blocked by column can simply be missing from the property map. A board, card or relation that reports as missing while you can see it in Notion almost always means the connection was never added to it.

Step 3: Connect in Kadmo

1. Open Integrations → Issue Tracking → Notion.
2. Paste the secret into Integration Token. There is no workspace URL to enter — the token identifies the workspace.
3. Optionally set a Default data source: the board whose statuses and types are offered when nothing else names one. A Notion board's columns are its own, so there is no workspace-wide list to fall back on.
4. Press Save, then Test Connection.

The test answers Connected as … — N databases shared and lists them under Shared databases. That list is the real result: Connected as … — nothing is shared with this connection yet means the token works but nothing will sync — go back to Step 2.

The first successful test also creates an automation called Assigned to Kadmo Agent (Notion): when a card's people property is set to the agent, the card is pooled in Tasks and auto-approved, and the playbook is chosen by the card's type. It is an ordinary rule — edit its filters and approval, disable or delete it under Automations. Disabling is the lasting opt-out; a deleted rule comes back the next time an Admin tests the connection.

Saving the token also delivers it to your agents, so their own reads and comments reach the board.

Step 4: Link a board to a workspace

1. Open the workspace's edit page and find the Work intake card (see Workspaces). If the account has more than one tracker connected, pick Notion first.
2. Choose a Notion data source from the list. Pick it rather than typing it — a data source id is a long opaque id. A database with several data sources lists each one separately; pick the one this workspace tracks. One data source per workspace.
3. Review the Notion property map that appears below. On a workspace that is already linked, press Show the property map to read it — merely opening the page never spends a live schema read.

The property map

Notion has no fixed vocabulary: the status column may be called Stage, there may be two people columns. Kadmo reads the board you built — a board view's grouping is the strongest hint about which column is the workflow — and shows which column plays which role.

Role	What it is for
Title	The ticket summary — required before anything can be created
Ticket key	The human-facing key from a unique-id column (for example ENG-17); cards without one use their page id
Status	The workflow column — required before anything can be moved
Type	Story, bug, task; without it cards carry no type
Assignee	Who owns the card; without it work lands unassigned
Blocked by	The dependency relation that holds work back
Parent	The parent relation used to group work
Verdict ledger	Where Kadmo records step verdicts — add a rich-text column named Kadmo Verdict and it is picked up
Priority	The urgency column (a select or status); without it cards rank as medium

Each row has a state: discovered (read off the board), assumed (a recommendation you can accept or change), ambiguous (a question you must answer — shown above the table) or absent (no such column, with the consequence). Your corrections are stored separately and survive Re-discover, which reads the schema again after you change the board.

The map stores Notion property ids, not names, so renaming a column is safe. Renaming an option is not: automation filters store option names, so re-pick a renamed status or type in the rule.

The workflow column

Use Notion's Status property type for the workflow column. Its To-do / In progress / Complete groups are how Kadmo knows what "done" means on your board. A board grouped by a plain select has no such groups, so the property map asks you to confirm what its options mean before Kadmo moves cards on it.

How card changes reach Kadmo

Kadmo checks every linked board for changes about every five minutes, newest edits first, and turns them into the same events the automation rules match on: Card created and Card updated (properties). There is nothing to switch on.

• No backfill. The starting point is the moment you linked the board. A card created before that never enters the pool this way, even if edited today. Add older cards from Tasks.
• No comment events. A page's edit time does not move on a comment, so Comment added is unavailable on Notion rules.
• Assigning is a property change. Notion has no "assigned" event — dropping the agent into a people property arrives as Card updated (properties). Keep that event ticked on an assign-the-agent rule.
• Rate limit. Notion allows about three requests per second per connection, shared by checks, reads and discovery. Kadmo paces itself under it, so a large board syncs gradually rather than failing.

What agents do on a card

Moment	What happens on the page
A step starts	The card moves to that step's status, when status sync is on
A step finishes	The agent posts one comment — what it did, the evidence, a verdict — and records the same verdict in the Kadmo Verdict column
The run resolves	The card moves to an option in the Complete group

The verdict is written twice because Notion's API returns only unresolved comments: resolving a thread would otherwise hide a step's verdict. A board without the verdict column still works; verdicts then stay comment-only.

A card's Blocked by relation becomes a task dependency when the blocking card is pooled too. Edits made by the connection itself are skipped, and a card with an active run never starts a second one.

Disconnect

Disconnect removes the token from Kadmo. The default data source and property maps are kept. Revoke the token in Notion too.

Troubleshooting

Symptom	Cause and fix
Test passes, but Shared databases is empty	No database is shared with the integration yet — see Step 2.
A step posts nothing, or its verdict is never seen	Insert comments or Read comments is off. Test does not check them.
People pickers come back empty	User information was never granted.
A board, card or relation reports as missing	It is not shared with the integration.
The status picker is empty or cards are not moved	The workflow column is a plain select, or two status columns compete. Answer the question in the property map, or convert the column to a Status property and press Re-discover.
A rule stopped matching after a board tidy-up	A status or type option was renamed. Re-pick it in the rule.
Nothing fires for cards that already existed	No backfill — add older cards from Tasks.
Changes take a few minutes to arrive	That is the five-minute check cycle.
No Assigned to Kadmo Agent (Notion) rule appeared	It is created by the first successful Test Connection run by an Admin. Run the test again.
Runs land in the wrong repository	Link the data source to the intended workspace on its Work intake card.