Developer guide
Plugins
A document says what a site will do; a plugin does it, every day: a scheduler, a tracker, a workflow, a dashboard. A plugin is a manifest (what it is, what it keeps, its pages and workflows, what it may read, what sets it going) and, optionally, functions compiled to WebAssembly that run in a sandbox. The platform runs the models, workflows and views itself: a plugin with no functions is possible.
![]()
The manifest (plugin.yaml)
| Key | What |
|---|---|
id, name, version, api |
Its id (lower case, permanent, yours once first submitted), name, semantic version, and the plugin API it targets (1) |
publisher |
{name, email} |
summary, description, category, icon, clause, requirements |
How it is listed: the menu clause it sits under, the requirement ids (from the Standards page) it helps meet |
licence, price |
standard; {model: free} |
permissions |
What it may read: documents:read:<kind> (an approved document), registers:read:<register> (an asset information register, accepted rows only) |
settings |
Its settings, set by site admins: {key: {type: integer|number|text|choice|bool, label, default, min, max, choices}} |
functions |
functions/main.wasm |
models |
Its records: {model: {label, plural, title, fields: {key: {type, label, required, readonly, hidden, choices, model}}}}; field types text, long, number, integer, date, choice, bool, ref (to another model) |
workflows |
Per model: initial, states ({key: {label, closed}}) and transitions ({key, label, from: [...], to, requires: [fields], role}) |
views |
Its pages: {key, label, model, columns, sort, open_first, states: [...], actions: [...], record_actions: [...]}; open_first hides closed records until asked, states shows only records in those workflow states |
actions |
Buttons: {key, label, function, record: true} (a record action gets the record) |
events |
{when: document.approved, kind, function}, {when: record.saved, model, function}, {when: record.transition, model, to, function} |
schedules |
{key, label, daily_at: "05:40", function} (site time) or {key, label, every_hours: 6, function} |
The Controls tracker and the other built-in plugins (src/readiness/plugins/builtin/*/plugin.yaml) are
complete examples; their help pages are written from their manifests.
Functions
A function is a WebAssembly export that takes JSON and returns JSON. It gets:
- from an action:
{"site": ..., "record": {...}}(for a record action); - from an event:
{"event": "document.approved", "kind": ..., ...}or{"event": "record.saved" | "record.transition", "record": {...}, ...}; - from a schedule:
{"site": ...}.
It returns {"ok": true, "message": "..."}: the message is shown to the person who pressed the button, and kept in the
plugin's Activity.
The host API
Everything a function needs it asks the platform for, through one import, amt.host, with a request
{"op": ..., ...}:
op |
Arguments | Returns |
|---|---|---|
now |
{now, today} (today in the site's time zone) |
|
settings |
{settings}: the site's values of the plugin's settings |
|
log |
message |
Writes to the plugin's Activity |
standards |
The standards the company applies | |
documents.get |
kind |
The approved document ({document, id, title, approved_at}); needs documents:read:<kind> |
registers.list |
register, limit |
{rows}: the register's accepted rows; needs registers:read:<register> |
records.list |
model, state, where |
{records} |
records.get |
model, id |
{record} |
records.create / records.update / records.delete |
model, data, id, state |
{id} / {ok} |
propose |
title, summary, changes |
A proposal for people to accept or decline (below) |
A request it is not allowed is refused with {"error": "..."}.
Limits
Each call: about 2,000,000,000 instructions of fuel, 5 seconds, 64 MB of memory, 5,000 host requests and 2,000 records written. A function that breaks a limit is stopped; the failure is in its Activity and on Tasks.
Proposals
A plugin that keeps records drawn from a document should propose them rather than write them: each change
({op: create|update|delete, model, id, data, why}) is listed on the plugin's Proposals tab for a person to accept
(all, or some) or decline. amt_plugin::sync_changes works out the changes between the records a plugin has and the ones a
document now calls for, so a document approved again proposes only what changed.
The Rust SDK (plugins/sdk-rust, crate amt_plugin)
handler!(export_name, function) |
Exports a fn(Value) -> Result<Value, String> as a function the manifest can name |
call(op, args) |
A host request |
approved(kind), records(model), today() |
The approved document (or None), a model's records, today as a day number |
sync_changes(existing, wanted, model, source, initial, ...) |
The creates, updates and deletes that bring the records in line with what a document wants |
propose(title, summary, changes, none) |
Proposes them (or answers none when there is nothing to change) |
flag(model, record, late) |
Sets a record's overdue flag when it changed |
days(date), date(day), interval_days("every 3 months"), entries(text), text(value, key), key_of(parts) |
Dates, intervals, lists and keys |
Any language that compiles to WebAssembly will do. The ABI: the module exports memory, amt_alloc(size: i32) -> i32 and
each function as name(ptr: i32, len: i32) -> i64 (UTF-8 JSON in at ptr; returns (out_ptr << 32) | out_len), and
imports amt.host(ptr: i32, len: i32) -> i64 the same way.
From the template to the marketplace
Copy
plugins/template: change theid,nameandpublisher; write the manifest. The template's functions count the open items (an action) and give an item saved without a due date one a week out (an event):use amt_plugin::{call, handler, json, text, Value}; fn count_open(_input: Value) -> Result<Value, String> { let items = call("records.list", json!({"model": "item"}))?["records"].as_array().cloned().unwrap_or_default(); let open = items.iter().filter(|r| r["state"] != "closed").count(); Ok(json!({"ok": true, "message": format!("{open} open item(s).")})) } fn item_saved(input: Value) -> Result<Value, String> { let r = &input["record"]; if text(&r["data"], "due").is_empty() { let today = call("now", json!({}))?["today"].as_str().unwrap_or("").to_string(); if let Some(d) = amt_plugin::days(&today) { call("records.update", json!({"model": "item", "id": r["id"], "data": {"due": amt_plugin::date(d + 7)}}))?; } } Ok(json!({"ok": true})) } handler!(count_open_fn, count_open); handler!(item_saved_fn, item_saved);Build:
rustup target add wasm32-unknown-unknown, thencargo build --release --target wasm32-unknown-unknownand copy the.wasmtofunctions/main.wasm(plugins/build.shdoes this for the plugins in this repository).Check:
python -m readiness.cli plugin-check .: the manifest, as review will.Try it in a test:
tests/test_plugins.pyandtests/test_roadmap_plugins.pyshow how to install a plugin in a test site, approve a document and accept its proposals).Pack and submit:
python -m readiness.cli plugin-pack . -o my-plugin-0.1.0.amtplugin, then submit it on the publisher portal. The automated checks run at once (the bundle, the manifest, the id is yours, the version is newer, no secrets, a dry run of every function); then a platform administrator reviews it.
Built-in plugins
The drawing register and the asset information pages are native plugins (runtime: native): the platform's own code,
installed per site like any plugin, with pages instead of views, requires between them, and hooks to export and
delete their data (readiness/plugins/native.py). The eight sandboxed plugins in src/readiness/plugins/builtin/ are
IMS Creator's own, built from plugins/<id>/ with the same SDK as anyone's.
See also
- Plugins (installing and using them) · Publisher portal ·
docs/PLUGINS.mdfor the design