Docs / Connecting a custom system

Connecting a custom system

For anything not built in — map any JSON API yourself, no code required.

For an internal tool, a niche tracker, or any other API Z3NTRA doesn't know about, add a connection with type Custom / Other and map its JSON shape by hand. You'll want to be comfortable reading that API's own documentation.

Set up

1. API base URL and List path — the GET request that returns your tasks, e.g. https://api.example.com + /v1/tasks?assignee=me.
2. Items path — a dot-path to the array in the response (e.g. data.items), or leave blank if the response itself is the array.
3. Field names — ID field, Title field, Description field, Status field, Due date field, Priority field, Assignee field, URL field — each a dot-path into one item.
4. Status mapping (JSON) — maps the API's raw status text onto Z3NTRA's four statuses, e.g. {"Open": "todo", "Working": "in_progress", "Done": "done"}. Anything not listed is guessed from the text with the same fuzzy matching every other connector falls back on.
5. Auth header name / Auth header prefix / the API token credential — sent as <header name>: <prefix><token> on every request. Leave the token blank for an API that needs no auth.

Write-back (optional)

Leave Update path blank for a read-only connection. To enable writing back:

• Set Update path (e.g. /v1/tasks/{id}, with {id} substituted), Update HTTP method, and an Update body template.
• The template is a JSON body with {{title}}, {{description}}, {{status}}, {{dueDate}}, {{priority}} placeholders, filled in with the edited values (or null for anything not part of that particular edit).
• Status is reverse-mapped through the same Status mapping JSON — make sure every status you want to write back has an entry there.

You can add as many custom connections as you like, each pointed at a different API — the mapping lives on the connection, not in code.