NotionSync 0.0.2

Queue processing from a URL

Until now the Notion sync queue could only be processed from the command line:

./cli notionsync:process-queue

That left out hosting providers which do not allow running processes from the CLI, where the plugin queued changes but never got to send them to Notion. This release adds an equivalent HTTP trigger, following the same pattern as Kanboard's own cronjob URL (CronjobController).

Usage

Both forms are equivalent and call the same action:

https://domain.tld/notionsync/cron?token=TOKEN
https://domain.tld/?controller=NotionCronjobController&action=run&plugin=NotionSync&token=TOKEN

The first one requires URL rewriting to be enabled (ENABLE_URL_REWRITE); the second one always works.

TOKEN is Kanboard's global webhook token, the one shown under Settings → Webhooks. There is no new credential to generate or manage.

Both URLs, already filled in with the instance's real token, are shown under Settings → NotionSync, ready to copy.

Any HTTP client can trigger them, whether it is the cron feature of your hosting panel or an external service:

*/5 * * * * wget -q -O - "https://domain.tld/notionsync/cron?token=TOKEN" >/dev/null 2>&1

Optional parameters

Parameter	Default	Description
limit	20	Jobs per run (maximum 500)
delay	350	Pause in milliseconds between calls to Notion

The default limit is 20 rather than the 50 used by the CLI: the console has no time cap, but an HTTP request does, and max_execution_time is typically 30 s on exactly the hosts that force you to use this route. With 20 jobs and a 350 ms pause the accumulated wait is 7 s, leaving room for the calls to Notion. The controller also tries to lift the cap with set_time_limit() where the host allows it.

A request cut short by the time limit breaks nothing: every job is committed to the database as soon as it finishes, so whatever was already synced stays synced and the rest is picked up by the next run.

Response

The response is text/plain with the command output, including the Processed | Synced | Failed line, because a cronjob triggered by URL has no stdout to look at and that text is all the triggering service records in its log.

• 200 — the endpoint ran. A failed job does not return an HTTP error, so that a transient Notion issue does not trip your monitor's alerts: the next run already covers the retry.
• 403 — the token does not match, is missing, or the instance has no webhook_token configured.

Security

• The route is exposed as public only for the run action, never the whole controller.
• The token is compared with hash_equals(), same as in the core.
• If the instance has no webhook_token, the URL returns 403 instead of being left open.

Upgrading from 0.0.1

Replace the plugins/NotionSync folder and you are done. There is no database migration, and the console command is unchanged: anyone already running the CLI cronjob does not need to touch anything.

Other changes

• New Queue processing section on the plugin settings screen, with the crontab example and both URLs.
• New translations for es_ES and es_VE.
• README expanded with the URL cronjob documentation.

Compatibility: Kanboard >= 1.2.0

NotionSync 0.0.1

First public release.

NotionSync mirrors your Kanboard tasks into a Notion database: when a task is
created in a configured project, the plugin creates a page in your Notion
"Tasks" database, keeps its title in sync, and marks it when the task is
removed.

Features

• Per-project property mapping. Each project defines which Notion
  properties to fill, their type, and a text template for the value. Projects
  with no mapping are left untouched — no API calls at all.
• Supported property types: title, rich_text, select,
  multi_select, status, date, url and relation.
• Template variables: {{title_task}}, {{task_id}}, {{task_url}},
  {{project_name}}, {{created_at}}, {{assignee}} and {{description}},
  freely mixed with plain text.
• Relation fields resolve by exact title match (case and whitespace
  sensitive) against a related database configured per field.
• Title updates. Editing a task in Kanboard updates only the title
  property of its Notion page; no other property is touched.
• On task deletion, a configurable property is set on the Notion page
  (for example Status = Cancelled). The page is never deleted or archived.
• Background queue + CLI command (notionsync:process-queue) meant to be
  run from cron, so Notion never blocks task creation in Kanboard.
• Manual retry button on the task view when a sync is pending or failed,
  which runs the call synchronously and reports the result immediately.
• Encrypted token. The Notion integration token is stored with AES-256-GCM,
  never in plain text.
• English and Spanish (es_ES) translations included.

Requirements

• Kanboard >= 1.2.0
• PHP with the cURL and OpenSSL extensions
• Outbound network access to api.notion.com
• A Notion internal integration, with the target databases shared with it
• A cron entry to run the queue command

Installation

Download NotionSync-0.0.1.zip below and extract it into plugins/, or
install it from the Kanboard Plugin Directory. Then set the integration token
and the database ID in Settings → NotionSync, and map the properties in
Project → Notion synchronization.

Things to know

• This plugin overrides the core TaskModel to detect task deletion, which
  Kanboard does not emit an event for. It may conflict with other plugins that
  override the same class.
• status options are not auto-created by the Notion API, so the value you
  configure (e.g. Cancelled) must already exist in your database. select
  and multi_select options are created automatically.
• Notion limits text properties to 2000 characters. The plugin does not
  truncate: it reports the error and leaves the task pending.
• The plugin targets Notion API version 2022-06-28.

Not included in this version

Two-way sync, retroactive sync of tasks created before installing the plugin,
automatic retries (retry is always manual), and assignee mapping to Notion
users.