Workflon in a Notes App

Overview

In this guide, you’ll wire up Workflon to a notes application so users can create and update notes using natural language. You will:

• Embed the Workflon widget with your app’s public key.
• Define actions like createNote and updateNote.
• Provide context (list of notes) for grounding.
• Validate and update state securely in response to copilot actions.

Preview the experience at /notes-demo.

Prerequisites

• An Workflon organization and app with a valid public key (pk_*)
• A notes app UI (React examples below)
• Ability to call your backend to persist changes

1) Add the Script

Place the script in your page (or inject after mount):

<script src="/api/script/YOUR_PUBLIC_KEY" async></script>

useEffect(() => {
  const pk = process.env.NEXT_PUBLIC_WORKFLON_PUBLIC_KEY;
  if (!pk) return;
  const id = "-script";
  if (!document.getElementById(id)) {
    const s = document.createElement("script");
    s.id = id;
    s.async = true;
    s.src = `/api/script/${pk}`;
    document.body.appendChild(s);
  }
}, []);

2) Define Notes Actions

Design clear, minimal actions and return confirmations. Example:

declare global {
  interface Window {
    Workflon?: {
      setActions: (
        actions: Record<string, (params: any) => Promise<any>>,
      ) => void;
      setUserContext: (ctx: Record<string, any[]>) => void;
      show: () => void;
    };
  }
}
 
window.Workflon?.setActions({
  createNote: async ({ title, category, content }) => {
    // Validate params, create via API, update UI
    return `Created note: ${title}`;
  },
  updateNote: async ({ noteId, title, content, category, dueDate }) => {
    // Partial update; persist to backend; update UI
    return `Updated note ${noteId}`;
  },
});

Param tips:

• Use human-friendly names (title, content, category).
• Support partial updates for flexibility.
• Validate enums like category and dueDate formats before persisting.

3) Provide Context

Supply a compact view of your notes so the copilot can reason about them:

window.Workflon?.setUserContext({
  notes: notes.map(({ id, title, category }) => ({ id, title, category })),
});

Update context after actions to reflect the latest state. Include IDs and key fields; avoid large bodies when not required.

4) UX Hooks

• Add a floating button or keyboard shortcut to call window.Workflon?.show().
• After createNote, select and scroll to the new note.
• After updateNote, flash a success toast.
• Provide clear error messages when validation fails.

5) Security & Reliability

• Validate on the server (never trust client-only checks).
• Enforce authorization per user/organization.
• Make action handlers idempotent where applicable.
• Log executions and errors for debugging.

End-to-end Example

The /notes-demo shows a working example of:

• Script injection
• Actions (createNote, updateNote)
• setUserContext with note summaries

Use it as a starting point and adapt to your storage/API.

Troubleshooting

• Copilot not loading: confirm the public key and script URL.
• Actions not fired: ensure setActions runs after script load.
• Context stale: re-run setUserContext after action side-effects.