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.

A plugin's page

Sandbox (wasmtime): nofiles, no network, no clockPlatformevent, schedule or button:JSON inamt.host requestschecked against thepermissions consented toJSON out: {ok, message}

Manifest: models, workflows, views, actions, events, schedules, settings, permissions

Pages: tables, record panels, Proposals, Activity

Engine: records, workflows, proposals, events, schedules

Host API: now, settings, log, standards, documents.get, registers.list, records.*, propose

Functions (main.wasm)

Approved documents and registers

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

cargo build --release --target wasm32-unknown-unknown

readiness plugin-check .

readiness plugin-pack . -o my-plugin-0.1.0.amtplugin

Submit on the publisher portal

Automated checks, then review

Signed and listed in every company's marketplace

  1. Copy plugins/template: change the id, name and publisher; 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);
  2. Build: rustup target add wasm32-unknown-unknown, then cargo build --release --target wasm32-unknown-unknown and copy the .wasm to functions/main.wasm (plugins/build.sh does this for the plugins in this repository).

  3. Check: python -m readiness.cli plugin-check .: the manifest, as review will.

  4. Try it in a test: tests/test_plugins.py and tests/test_roadmap_plugins.py show how to install a plugin in a test site, approve a document and accept its proposals).

  5. 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.md for the design