Recipes — End-to-End Worked Examples#

plugin-example/
├── kizen.json
├── releaseNotes/
│   └── 1.0.0.md
└── src/
    ├── thumbnail.png                 # required to publish; PNG at the entry root
    └── blocks/statusCard/
        ├── config.json
        ├── script.js
        ├── eventScripts/
        │   ├── render.js             # the single painter
        │   └── refresh.js
        └── styles.css

{
  "name": "Example Plugin",
  "api_name": "example_plugin",
  "version": "1.0.0",
  "description": "A status card block for dashboards and homepages.",
  "engine": "1.0.0",
  "entry": "src/",
  "release_notes_directory": "releaseNotes/",
  "published": false,
  "developer_business_id": { "go": "<your-developer-business-id>" }
}

{
  "name": "Status Card",
  "api_name": "status_card",
  "types": ["dashboards", "homepages"],
  "min_w": 3,
  "max_w": 8,
  "min_h": 3,
  "max_h": 8,
  "recommended_height": 300
}

// Mount: shell + delegate. All markup lives in eventScripts/render.js.
this.outputUI(`<div class="sc-card sc-card--loading">Loading status…</div>`);
this.runEventScript("render", { reason: "mount" });

// Single painter. Event scripts are isolated workers — small helpers like esc()
// are duplicated per script by design; there are no shared modules.
const esc = (text) =>
  String(text).replace(
    /[&<>"']/g,
    (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c],
  );

const name = this.currentUser?.profile?.first_name || "there";
const refreshedAt = this.sessionData?.scRefreshedAt;

this.outputUI(`
  <div class="sc-card">
    <div class="sc-head">
      <span class="sc-title">Status</span>
      <button class="sc-btn" data-script="refresh">Refresh</button>
    </div>
    <p class="sc-note">Hello, ${esc(name)} — everything is running.</p>
    ${
      refreshedAt
        ? `<p class="sc-stamp">Refreshed ${esc(new Date(refreshedAt).toLocaleTimeString())}</p>`
        : ""
    }
  </div>
`);

// State-changing scripts never paint; they record state and re-enter the painter.
this.setSessionData({ scRefreshedAt: Date.now() });
this.runEventScript("render", { reason: "refresh" });

/* Engine-scoped to this block's markup — plain selectors are safe. */
.sc-card {
  margin: 4px;                      /* inset so the self-painted shadow isn't clipped */
  height: calc(100% - 8px);
  box-sizing: border-box;
  display: flex;
  flex-direction: column;
  padding: 14px;
  background: #ffffff;
  border-radius: 8px;
  box-shadow: 0 1px 4px rgba(0, 0, 0, 0.18);   /* tight shadow that fits the 4px inset */
}

/* The host reset leaks in — explicit px font-size/line-height on every text element. */
.sc-title { font-size: 14px; line-height: 20px; font-weight: 700; color: #1e293b; }
.sc-note  { font-size: 13px; line-height: 18px; color: #475569; margin: 10px 0 0; }
.sc-stamp { font-size: 10px; line-height: 14px; color: #94a3b8; margin: auto 0 0; }

.sc-head { display: flex; align-items: center; justify-content: space-between; }

/* data-script buttons must contain text only — a child element swallows the click. */
.sc-btn {
  font-size: 12px;
  line-height: 16px;
  padding: 4px 10px;
  border: none;
  border-radius: 4px;
  background: #4f46e5;
  color: #ffffff;
  cursor: pointer;
}
.sc-card--loading {
  align-items: center;
  justify-content: center;
  font-size: 12px;
  line-height: 16px;
  color: #64748b;
}

Initial release: a Status Card block for dashboards and homepages.

plugin-example/
├── kizen.json                        # + services[], version bumped to 1.1.0
├── releaseNotes/
│   └── 1.1.0.md                      # required — the bump selects this file
└── src/
    └── blocks/providerProfile/
        ├── config.json
        ├── script.js
        ├── eventScripts/
        │   ├── render.js
        │   └── connect.js
        └── styles.css                # card chrome as in Recipe 1 (omitted here)

{
  "name": "Example Plugin",
  "api_name": "example_plugin",
  "version": "1.1.0",
  "description": "Shows your connected provider profile on a dashboard.",
  "engine": "1.0.0",
  "entry": "src/",
  "release_notes_directory": "releaseNotes/",
  "services": [
    {
      "service_name": "provider_user",
      "display_name": "Provider (my account)",
      "auth_type": "oauth",
      "auth_level": "user",
      "scope": "user-account-only",
      "required_entitlement": null,
      "base_service_url": "https://api.provider.example.com",
      "auth_credentials": {
        "client_id": { "encrypted": true, "value": "<base64 envelope>" },
        "client_secret": { "encrypted": true, "value": "<base64 envelope>" },
        "scopes": "profile.read",
        "authorize_url": "https://auth.provider.example.com/oauth2/authorize",
        "token_url": "https://auth.provider.example.com/oauth2/token",
        "content_type": "application/x-www-form-urlencoded",
        "token_field_name": "access_token",
        "default_token_expiry": 3600,
        "authorize_params": { "access_type": "offline", "prompt": "consent" }
      }
    }
  ]
}

{
  "name": "Provider Profile",
  "api_name": "provider_profile",
  "types": ["dashboards", "homepages"],
  "min_w": 3,
  "max_w": 8,
  "min_h": 3,
  "max_h": 8,
  "recommended_height": 300
}

this.outputUI(`<div class="pp-card pp-card--loading">Loading profile…</div>`);
this.runEventScript("render", { reason: "mount" });

const esc = (text) =>
  String(text).replace(
    /[&<>"']/g,
    (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c],
  );

const [profile, error] = await this.getWithErrors(
  this.getServiceUrl("provider_user", "/v1/me"),
);

if (error) {
  // 503 from the proxy = no usable stored token for this employee. Other employees
  // being connected does not help — user-level tokens are per employee.
  if (error.upstreamStatus === 503 || error.proxyStatus === 503) {
    this.outputUI(`
      <div class="pp-card">
        <p class="pp-note">Connect your Provider account to see your profile here.</p>
        <button class="pp-btn" data-script="connect">Connect Provider</button>
      </div>
    `);
    return;
  }

  // Any other failure is an expected upstream problem: branch on upstreamStatus
  // (the vendor's real status), not proxyStatus (200 whenever the proxy reached it).
  this.console.warn("Provider Profile: fetch failed", error);
  this.outputUI(`
    <div class="pp-card">
      <p class="pp-note">Could not reach Provider (HTTP ${esc(error.upstreamStatus ?? "?")}).</p>
      <button class="pp-btn" data-script="render">Try again</button>
    </div>
  `);
  return;
}

this.outputUI(`
  <div class="pp-card">
    <div class="pp-head">
      <span class="pp-title">${esc(profile?.display_name ?? "Connected")}</span>
      <button class="pp-btn" data-script="render">Refresh</button>
    </div>
    <p class="pp-note">${esc(profile?.email ?? "")}</p>
  </div>
`);

this.authorize("provider_user");

this.showToast("Finish connecting in the new tab, then check the connection.", {
  variant: "alert",
});

// Repaint with a re-check affordance. "Check connection" simply re-enters render:
// if the user completed the flow, the /v1/me call now succeeds; if not, 503 again
// and the connect card comes back.
this.outputUI(`
  <div class="pp-card">
    <p class="pp-note">Waiting for you to finish authorizing in the other tab…</p>
    <button class="pp-btn" data-script="render">Check connection</button>
  </div>
`);

Adds a Provider Profile block backed by a user-level OAuth service. Each user connects their own
provider account from the block.

plugin-example/
├── kizen.json                        # + base_config.secrets
└── src/
    └── automationSteps/
        ├── dbRead/
        │   ├── config.json
        │   └── script.py
        └── dbWrite/
            ├── config.json
            └── script.py

{
  "base_config": { "secrets": ["connection_json"] }
}

// flat
{ "host": "db.example.com", "port": 5432, "user_name": "reporting", "password": "…" }

// keyed by environment — selected per step with the connection_secret_tag input
{
  "production_db": { "host": "db.example.com",       "port": 5432, "user_name": "…", "password": "…" },
  "staging_db":    { "host": "db-stage.example.com", "port": 5432, "user_name": "…", "password": "…" }
}

{
  "name": "Read Data",
  "api_name": "db_read",
  "plugin_description": "Example database connector.",
  "action_description": "Connects to the configured database and runs a read-only query. SELECT only — write statements are rejected; use Write Data to modify rows. With Return Single Value on, the query must return exactly one row and one column. Multi-row results are returned as a single stringified value.",
  "action_type": "example_plugin_db_read",
  "runtime": "python-3-13",
  "secrets": ["connection_json"],
  "inputs": [
    { "name": "database", "label": "Database", "data_type": "string", "required": true, "input_source": "static_value", "script_alias": "database" },
    { "name": "query", "label": "Query", "data_type": "string", "required": true, "input_source": "variable", "script_alias": "query" },
    { "name": "return_single_value", "label": "Return Single Value", "data_type": "boolean", "required": true, "input_source": "static_value", "default": true, "script_alias": "return_single_value" },
    { "name": "connection_secret_tag", "label": "Connection Secret Tag", "data_type": "string", "required": false, "input_source": "static_value", "script_alias": "connection_secret_tag" }
  ],
  "outputs": [
    { "name": "result", "label": "Result", "data_type": "string", "required": true, "input_source": "variable", "script_alias": "result", "conflict_resolution": "overwrite", "create_field_options": false }
  ]
}

# Example Plugin · Agentic Workflow Step · Read Data
#
# Runs a read-only query against the database described by the connection_json secret.
# The secret is a flat {host, port, user_name, password} document, or a map of those
# documents keyed by environment tag (selected with the connection_secret_tag input).

import json
import re
import time

import psycopg
from psycopg.rows import dict_row

WRITE_STATEMENT = r"^\s*(INSERT|UPDATE|DELETE|DROP|ALTER|TRUNCATE|CREATE|GRANT|REVOKE|COPY|CALL|DO)\b"
REQUIRED_KEYS = ("host", "port", "user_name", "password")

# Admins paste connection JSON out of documents and chat clients, which substitute
# curly quotes; json.loads rejects them with an opaque error. Normalize first.
SMART_QUOTE_MAP = str.maketrans({
    "“": '"', "”": '"', "„": '"', "‟": '"',
    "‘": "'", "’": "'", "‛": "'",
})


def load_connection():
    """Resolve the connection document, tolerating smart quotes and the tag-nested shape."""
    # Suffix-match the namespaced key ({plugin_api_name}__connection_json) so preview
    # builds, which suffix the plugin api_name, still find it.
    key = next((k for k in secrets if k.endswith("connection_json")), None)
    if not key or not secrets[key]:
        raise ValueError(
            "Example Plugin error: not_configured — the connection_json secret is empty. "
            "Set it under the plugin's integration secrets."
        )

    document = json.loads(secrets[key].translate(SMART_QUOTE_MAP))

    # Optional inputs are ABSENT (AttributeError), not None — always getattr.
    tag = getattr(inputs, "connection_secret_tag", None)
    if tag:
        if tag not in document:
            raise ValueError(
                f"Example Plugin error: bad_tag — tag {tag!r} is not in the connection secret."
            )
        document = document[tag]

    missing = [k for k in REQUIRED_KEYS if k not in document]
    if missing:
        raise ValueError(
            f"Example Plugin error: bad_secret — missing key(s): {', '.join(missing)}"
        )
    return document


def connect_with_retry(conn_info, database):
    """One retry on a transient connect failure, sized well inside the 30s budget."""
    for attempt in (1, 2):
        try:
            return psycopg.connect(
                host=conn_info["host"],
                port=conn_info["port"],
                dbname=database,
                user=conn_info["user_name"],
                password=conn_info["password"],
                row_factory=dict_row,
                connect_timeout=10,
            )
        except psycopg.OperationalError as exc:
            if attempt == 2:
                raise ValueError(
                    f"Example Plugin error: connect_failed — could not reach the database "
                    f"({exc}). Check the connection secret and network access."
                )
            outputs.log(f"Connect attempt {attempt} failed ({exc}); retrying once.")
            time.sleep(2)


connection_info = load_connection()
query = inputs.query                          # required inputs are guaranteed present

# Guardrail: reject obvious write statements before opening a connection. The session
# is also forced read-only below. Neither is a security boundary — the query text runs
# verbatim, so this step is by construction an arbitrary-SELECT surface; restrict the
# database user's grants.
if re.match(WRITE_STATEMENT, query, re.IGNORECASE):
    raise ValueError(
        "Example Plugin error: write_rejected — write statements are not allowed here. "
        "Use the Write Data step."
    )

outputs.log(f"Connecting to {connection_info['host']}:{connection_info['port']}/{inputs.database}")

try:
    with connect_with_retry(connection_info, inputs.database) as connection:
        with connection.cursor() as cursor:
            cursor.execute("SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY")
            cursor.execute("SET default_transaction_read_only = on")
            cursor.execute(query)
            rows = cursor.fetchall()

            if not rows:
                outputs.log("Query returned no rows.")
                outputs.result = ""
            elif inputs.return_single_value:
                if len(rows) != 1 or len(rows[0]) != 1:
                    raise ValueError(
                        "Example Plugin error: shape_mismatch — Return Single Value is on, "
                        f"but the query returned {len(rows)} row(s) and "
                        f"{len(rows[0]) if rows else 0} column(s)."
                    )
                outputs.result = str(next(iter(rows[0].values())))
            else:
                outputs.log(f"Query returned {len(rows)} row(s).")
                # A string output cannot express structure: multi-row results are the
                # stringified list of dicts, and downstream steps must parse it. Prefer
                # return_single_value or an aggregating query when feeding another step.
                outputs.result = str(rows)

except psycopg.Error as exc:
    raise ValueError(f"Example Plugin error: database_error — {exc}")

{
  "name": "Write Data",
  "api_name": "db_write",
  "plugin_description": "Example database connector.",
  "action_description": "Runs a write statement (INSERT/UPDATE/DELETE) against the configured database and commits it. This step is privileged and has no guardrail — the statement runs verbatim as the configured database user. Outputs the affected row count.",
  "action_type": "example_plugin_db_write",
  "runtime": "python-3-13",
  "secrets": ["connection_json"],
  "inputs": [
    { "name": "database", "label": "Database", "data_type": "string", "required": true, "input_source": "static_value", "script_alias": "database" },
    { "name": "statement", "label": "Statement", "data_type": "string", "required": true, "input_source": "variable", "script_alias": "statement" },
    { "name": "connection_secret_tag", "label": "Connection Secret Tag", "data_type": "string", "required": false, "input_source": "static_value", "script_alias": "connection_secret_tag" }
  ],
  "outputs": [
    { "name": "rows_affected", "label": "Rows Affected", "data_type": "number", "required": false, "input_source": "variable", "script_alias": "rows_affected", "conflict_resolution": "overwrite", "create_field_options": false }
  ]
}

# Example Plugin · Agentic Workflow Step · Write Data
#
# Privileged: the statement runs verbatim. The split into a guarded read step and an
# unguarded write step is deliberate — the action_description says so, and the real
# control is the database user's grants.

import json
import time

import psycopg

# ... load_connection(), connect_with_retry(), SMART_QUOTE_MAP: copied from dbRead ...

connection_info = load_connection()

try:
    with connect_with_retry(connection_info, inputs.database) as connection:
        with connection.cursor() as cursor:
            cursor.execute(inputs.statement)
            outputs.rows_affected = cursor.rowcount
        connection.commit()
except psycopg.Error as exc:
    raise ValueError(f"Example Plugin error: database_error — {exc}")

outputs.log(f"Statement affected {outputs.rows_affected} row(s).")

plugin-example/
└── src/
    ├── blocks/signupLauncher/
    │   ├── config.json
    │   ├── script.js
    │   ├── eventScripts/
    │   │   ├── render.js
    │   │   └── launch.js             # opens the wizard, awaits the result
    │   └── styles.css                # card chrome as in Recipe 1 (omitted here)
    └── views/signupwizard/
        ├── config.json
        ├── script.js
        ├── eventScripts/
        │   ├── step1.js
        │   ├── step2.js
        │   ├── finish.js
        │   └── cancel.js
        └── styles.css

{ "name": "Signup Wizard", "api_name": "signupwizard" }

this.outputUI(`<div class="wiz"><p>Loading…</p></div>`);
this.runEventScript("step1");

const esc = (s) =>
  String(s ?? "").replace(/[&<>"']/g, (c) =>
    ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);

// Repainted by "Back" with prior values on this.args.formData; empty on first paint.
// Every collected form value is ARRAY-WRAPPED (FormData.getAll semantics) — index [0]
// for single-value fields.
const prior = this.args.formData ?? {};
const name = prior["contact-name"]?.[0] ?? "";
const email = prior["contact-email"]?.[0] ?? "";

// Field names must never be bare DOM-property words ("name", "title", "action", …) —
// DOMPurify's clobbering protection silently strips them. Hyphenate.
this.outputUI(`
<form class="wiz" data-script="step2">
  <h2>New signup — step 1 of 2</h2>
  <label>Name <input type="text" name="contact-name" value="${esc(name)}" required /></label>
  <label>Email <input type="email" name="contact-email" value="${esc(email)}" required /></label>
  <footer>
    <button type="button" data-script="cancel">Cancel</button>
    <button type="submit">Next</button>
  </footer>
</form>
`);

const esc = (s) =>
  String(s ?? "").replace(/[&<>"']/g, (c) =>
    ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);

const fd = this.args.formData ?? {};
const name = fd["contact-name"]?.[0] ?? "";
const email = fd["contact-email"]?.[0] ?? "";
const hidden = `
  <input type="hidden" name="contact-name" value="${esc(name)}" />
  <input type="hidden" name="contact-email" value="${esc(email)}" />`;

this.outputUI(`
<div class="wiz">
  <h2>Confirm — step 2 of 2</h2>
  <p>Create signup for <strong>${esc(name)}</strong> (${esc(email)})?</p>
  <footer>
    <form data-script="step1">${hidden}<button type="submit">&larr; Back</button></form>
    <form data-script="finish">${hidden}<button type="submit">Create</button></form>
  </footer>
</div>
`);

const fd = this.args.formData ?? {};
const name = fd["contact-name"]?.[0]?.trim();
const email = fd["contact-email"]?.[0]?.trim();

const [created, err] = await this.postWithErrors("/records/signup_signup/add", {
  fields: [
    { name: "name", value: name },
    { name: "email", value: email },
  ],
});

if (err) {
  this.showToast(`Create failed: ${err.message}`, { variant: "failure", autohide: false });
  // Don't close — repaint the confirm step in place so the user can retry.
  this.runEventScript("step2", { formData: fd });
  return;
}

// closeModal resolves the opener's showViewInModal promise with these values.
this.closeModal({ recordId: String(created.id) }, false);

this.closeModal(undefined, true);

const result = await this.showViewInModal("signupwizard", {
  options: { frameless: true, size: "medium" },     // 900px; frameless = the view owns all chrome
});

if (result.canceled) {
  this.runEventScript("render", { reason: "canceled" });
  return;
}

// Frameless views resolve with exactly what they passed to closeModal — not formData.
this.setSessionData({ lastSignupId: result.values.recordId });
this.showToast(`Signup ${result.values.recordId} created.`, { variant: "success" });

// Sequential chaining is fine — the first modal has closed. Args must nest under
// config.args (top-level keys beside options are silently dropped); they merge over
// the view's injected business config, so this.config still resolves inside the view.
await this.showViewInModal("summaryview", {
  args: { recordId: result.values.recordId },
  options: { title: "What you created", confirmButton: { label: "Done" }, size: "small" },
});

this.runEventScript("render", { reason: "created" });

plugin-example/
├── kizen.json                        # + services[] (user-level OAuth, as in Recipe 2)
└── src/
    └── calendarSources/personal/
        ├── config.json
        ├── calendars.js              # → calendars_script
        └── events.js                 # → events_script

{
  "name": "Example Calendar",
  "api_name": "personal",
  "when": "Boolean({{userConfig.enableExternalCalendars}})"
}

// Lists the calendars the current user can enable in the Kizen calendar picker.
// Required per calendar: { id, name }. Optional: { description?, default? }.

// Per-user filtering from the user setup assistant. Multi-select config values are
// {label, value} option objects — map .value.
const allCalendarsEnabled = this.userConfig.enableAllCalendars ?? true;
const enabledIds =
  this.userConfig.enabledUserCalendars?.map((option) => option.value) || [];

const [data, error] = await this.getWithErrors(
  this.getServiceUrl("provider_user", "/v1/calendars"),
);

// Degrade, never throw: a thrown error is triaged as a PLATFORM problem, while [] is
// simply "no calendars". A proxy 503 additionally marks the source as needing
// re-authorization — the engine classifies it as an auth error, not a data failure.
if (error) {
  const message =
    typeof error === "string" ? error : (error?.message ?? JSON.stringify(error));
  this.console.error(`Example Calendar: failed to list calendars: ${message}`);
  return [];
}

// Validate the external response at the boundary.
if (!Array.isArray(data?.calendars)) {
  this.console.error(
    `Example Calendar: unexpected calendars response shape ${JSON.stringify(data)}`,
  );
  return [];
}

return data.calendars
  .map((calendar) => ({
    id: calendar.id,
    name: calendar.display_name,
    description: calendar.description,
    default: calendar.is_primary || false,      // pre-selects in the picker
  }))
  .filter((calendar) => allCalendarsEnabled || enabledIds.includes(calendar.id));

// Provider event shape assumed here: { id, subject, body_preview, web_url, is_all_day,
// start: { date? | date_time? }, end: { date? | date_time? }, show_as, ical_uid }.
// Adjust the field mapping to your vendor.

const { calendar_id, range_start, range_end } = this.args.calendar;

// All-day events carry a bare date; timed events carry a date_time with its own offset.
const isAllDayEvent = (event) =>
  Boolean(event.is_all_day || (event.start?.date && !event.start?.date_time));

// DST discipline: parse all-day DATES with this.createDateObject("YYYY-MM-DD") — it
// builds a LOCAL-midnight Date, so a DST boundary can never shift the day. Parse timed
// events with new Date(date_time); the timestamp carries its own offset. Never
// hand-assemble a timestamp without an offset.
const parseEventBounds = (event) => {
  try {
    if (isAllDayEvent(event)) {
      return {
        startDate: this.createDateObject(event.start.date),
        endDate: this.createDateObject(event.end.date),
      };
    }
    return {
      startDate: new Date(event.start.date_time),
      endDate: new Date(event.end.date_time),
    };
  } catch (ex) {
    // Drop one unparseable event (logged) rather than failing the whole list.
    this.console.warn(`Example Calendar: skipping event ${event.id} — bad start/end`, event);
    return {};
  }
};

// Page through results — a busy calendar exceeds one page, and unpaged results
// silently drop events.
const events = [];
let pageToken = "";

do {
  const query =
    `from=${encodeURIComponent(range_start)}&to=${encodeURIComponent(range_end)}` +
    (pageToken ? `&page_token=${encodeURIComponent(pageToken)}` : "");

  const [data, error] = await this.getWithErrors(
    this.getServiceUrl(
      "provider_user",
      `/v1/calendars/${encodeURIComponent(calendar_id)}/events?${query}`,
    ),
  );

  // Degrade to "no events" on any failure (a proxy 503 also flags the source
  // as unauthorized — see the doctrine in calendars.js).
  if (error) {
    const message =
      typeof error === "string" ? error : (error?.message ?? JSON.stringify(error));
    this.console.error(
      `Example Calendar: failed to list events for ${calendar_id}: ${message}`,
    );
    return [];
  }

  if (!Array.isArray(data?.events)) {
    this.console.error(
      `Example Calendar: unexpected events response shape ${JSON.stringify(data)}`,
    );
    return [];
  }

  events.push(...data.events);
  pageToken = data.next_page_token || "";
} while (pageToken);

return events
  .map((event) => {
    const { startDate, endDate } = parseEventBounds(event);
    if (!startDate || !endDate) {
      return null;
    }

    // Events Kizen itself synced into the provider carry an iCalUID of the form
    // "{activityId}--…". Populate activity_id so the Kizen calendar links the event
    // back to its activity instead of showing a duplicate.
    const activityId = event.ical_uid?.includes("--")
      ? event.ical_uid.split("--")[0]
      : undefined;

    return {
      id: event.id,                                   // required
      calendar_id,                                    // required — echo the arg
      title: event.subject,                           // required
      start_time: this.formatDateForResponse(startDate),  // required — epoch ms
      end_time: this.formatDateForResponse(endDate),       // required — epoch ms
      description: event.body_preview,
      url: event.web_url,
      activity_id: activityId,
      all_day: isAllDayEvent(event),
      busy: event.show_as !== "free",                 // map your vendor's free/busy model
    };
  })
  .filter((event) => event !== null);

plugin-example/
└── src/
    └── actions/logOutcome/
        ├── config.json
        └── script.js

{
  "name": "Log Outcome",
  "api_name": "log_outcome",
  "hint_object_name": "client_client"
}

// Example Plugin · Action · Log Outcome
//
// Prompts for an outcome, overwrites the record's `latest_outcome` field, appends a
// stamped copy to the multi-value `outcome_history` field, and repaints the page.
// Expected failures get a sticky failure toast and a return — never a throw, which
// would route to platform monitoring and show the user nothing.

// Normalize a *WithErrors error so a toast never shows "[object Object]".
const describeError = (error) =>
  typeof error === "string"
    ? error
    : (error?.message ?? (error ? JSON.stringify(error) : null));

const entity = await this.currentEntity();
if (!entity) {
  this.showToast("No record context available.", { variant: "failure", autohide: false });
  return;
}

const result = await this.dynamicPrompt({
  title: "Log Outcome",
  size: "small",
  confirmButton: { label: "Save", variant: "standard", color: "primary" },
  cancelButton: { label: "Cancel", variant: "text", color: "secondary" },
  content: [
    {
      type: "select",
      key: "outcome",
      label: "Outcome",
      required: true,
      widthPercent: 100,
      options: [
        { label: "Connected", value: "connected" },
        { label: "Left voicemail", value: "voicemail" },
        { label: "No answer", value: "no_answer" },
      ],
    },
    { type: "text", key: "note", label: "Note", widthPercent: 100 },
  ],
});

// Always guard canceled before touching values.
if (result.canceled) return;

// dynamicPrompt values are PLAIN (not array-wrapped): a text field is a string, and a
// select resolves to the whole {label, value} option object — read .value.
const outcome = result.values.outcome.value;
const note = (result.values.note ?? "").trim();

const stamped = `${new Date().toISOString()} — ${outcome}${note ? `: ${note}` : ""}`;

const [, patchError] = await this.patchWithErrors(
  `/records/${this.objectId}/${this.entityId}`,
  {
    fields: [
      // Overwrite: replaces whatever latest_outcome currently holds.
      { name: "latest_outcome", value: outcome },
      // Append: adds to the multi-value field without removing existing values.
      { name: "outcome_history", add_values: [stamped] },
    ],
  },
);

if (patchError) {
  this.console.log(
    `Log Outcome — write failed for record ${this.entityId}`,
    "error:", describeError(patchError),
  );
  this.showToast(`Could not save the outcome: ${describeError(patchError)}`, {
    variant: "failure",
    autohide: false,
  });
  return;
}

this.showToast("Outcome logged.", { variant: "success" });

// A write does not repaint anything. This is the line people forget — skipping it is
// why an action "didn't work" when it actually did.
this.refreshEntity();