form-manager

name

form-manager

description

Manage customer-facing forms and their submissions on the KnowUV backend. Use this skill whenever the user wants to: collect customer info via a landing page, view or export form submissions, set up a registration page (summer camp, product waitlist, event sign-up, course enrollment, etc.), submit form data to the knowuv.com backend, list forms, browse or delete submissions, or wire up an HTML landing page to a real backend. Also trigger when the user mentions SubmitForm, ListForm, form submissions, customer data collection, or any landing page that captures user information.

Form Manager Skill

This skill connects AI-generated landing pages to the KnowUV backend, enabling real customer data collection. When a user builds a registration or lead-capture page, this skill handles all backend interactions: submitting data, browsing submissions, and managing form lifecycle.

Setup: Read Credentials First

Before any API call, read credentials from config.ini (in the same directory as this SKILL.md). Parse KEY = VALUE lines, ignoring lines starting with #.

Required keys:

• USER_ID — the author ID sent with every form request
• USER_TOKEN — the API bearer token

If credentials are missing or still placeholder

If USER_ID is your_user_id_here or USER_TOKEN is your_token_here, pause and guide the user:

Setup needed before we can continue:

1. User ID: Find your numeric user ID at https://knowuv.com/admin/internal/profile (shown as "Account ID" or similar). Paste it here.
2. API Token: Visit https://knowuv.com/JZfdJ to get your token. Paste it here.

Once you share both, I'll save them to config.ini so you won't need to do this again.

After the user provides them, write both to config.ini:

USER_ID = <provided_id>
USER_TOKEN = <provided_token>

Confirm: "Saved! Your credentials are ready — let's continue."

---

Base URL & Request Format

• Host: https://api.knowuv.com
• Path: /knowuv.UserInteractionService/<Method>
• Method: Always POST
• Content-Type: application/json
• Auth header: Authorization: Token <USER_TOKEN>

All responses:

{ "code": 0, "msg": "...", <other fields> }

code = 0 is success. Non-zero means failure — show the user the msg in plain language.

code	meaning
0	Success
1	Invalid parameters
3	Server error — try again
4	Rate limited — wait a moment
7	Not found
9	Unauthorized — token may be wrong or expired
14	Insufficient balance

---

Key Concepts

Form Name (name)

A concise, descriptive identifier for the form. This is how you distinguish forms from one another — think of it like a filename. Examples: summer-camp-2024, product-waitlist-q3, contact-form-homepage.

• If the user doesn't provide one, generate a sensible name from their description (e.g., "summer camp registration page" → summer-camp-registration).
• Ask the user to confirm if unsure — the name is permanent and used in all future lookups.

Author (author)

Always the USER_ID from config.ini. This is the knowuv.com account that owns all forms created with this skill. Users never need to specify it.

Payload

The actual form submission data — a JSON-encoded string (not a nested object). Example:

"{\"name\": \"Alice\", \"email\": \"[e-mail]\", \"course\": \"Math\"}"

When generating landing pages, the HTML form's submit handler must serialize field values to JSON and pass the result as the payload string.

---

API Reference

Submit Form

Used by landing pages (or the agent on behalf of the user) to record a customer submission.

POST /knowuv.UserInteractionService/SubmitForm

{
  "name": "summer-camp-registration",
  "author": "<USER_ID>",
  "payload": "{\"student_name\":\"Alice\",\"grade\":\"5\",\"course\":\"Math\",\"parent_phone\":\"138xxxx\"}"
}

Response:

{ "code": 0, "msg": "OK", "submitId": "69cb65d684c94d414df5e88a" }

The submitId is a unique ID for this submission. Show it to the user as confirmation.

---

List Forms

Show all forms owned by the user.

POST /knowuv.UserInteractionService/ListForm

{
  "name": "",
  "author": "<USER_ID>",
  "page": 1,
  "page_size": 20
}

Filter by providing a partial name. Response data is a list of form objects with fields: name, author, submit_count, last_submit_time, ctime, id.

Present as a table: Form Name | Submissions | Last Activity | Created.

---

List Submissions for a Form

Browse all customer submissions for a specific form.

POST /knowuv.UserInteractionService/ListSubmitFormDetail

{
  "name": "summer-camp-registration",
  "author": "<USER_ID>",
  "page": 1,
  "page_size": 20
}

Response data is a list of submission records: id, payload (JSON string), user_id, ctime.

Parse each payload string and display as a readable table. If all submissions share the same keys, use them as column headers. Show ctime as a human-readable date.

---

Get Latest Submission

Quickly fetch the most recent submission for a form — useful for confirming a test submission went through.

POST /knowuv.UserInteractionService/GetLatestSubmitFormDetail

{
  "name": "summer-camp-registration",
  "author": "<USER_ID>",
  "payload": ""
}

Response data is a single submission record. Parse and display the payload as key-value pairs.

---

Delete a Form

Removes the form record (not its submissions — use DeleteSubmitFormDetail for those).

POST /knowuv.UserInteractionService/DeleteSubmitForm

{ "id": "<form_id>" }

The id comes from ListForm. Confirm with the user before deleting — this cannot be undone.

---

Delete a Submission

Removes a single customer submission record.

POST /knowuv.UserInteractionService/DeleteSubmitFormDetail

{ "id": "<submission_id>" }

The id comes from ListSubmitFormDetail. Confirm with the user before deleting.

---

Workflow: Wiring a Landing Page to the Backend

When the user has an AI-generated HTML landing page and wants customer submissions to reach the backend:

1. Choose a form name — ask the user or generate one from the page's purpose.
2. Inject the submit handler into the HTML. The handler should:
   • Collect all form field values as a plain JS object
   • Serialize it to a JSON string: JSON.stringify(formData)
   • POST to the SubmitForm endpoint with name, author, and payload
   • Show the user a success message with their submitId

Example fetch snippet to inject:

async function submitToKnowUV(formData) {
  const response = await fetch('https://api.knowuv.com/knowuv.UserInteractionService/SubmitForm', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Token YOUR_TOKEN_HERE'
    },
    body: JSON.stringify({
      name: 'FORM_NAME_HERE',
      author: 'USER_ID_HERE',
      payload: JSON.stringify(formData)
    })
  });
  const result = await response.json();
  if (result.code === 0) {
    return { success: true, submitId: result.submitId };
  } else {
    throw new Error(result.msg);
  }
}

Note on token in frontend HTML: The USER_TOKEN will be visible in client-side HTML. This is acceptable for internal/low-risk forms. For sensitive use cases, recommend the user proxy the submission through their own backend.

3. Test the integration — after the page is live, call GetLatestSubmitFormDetail to confirm a test submission arrived.
4. View results — direct the user to: https://knowuv.com/admin/internal/form_structure for a UI to browse and export all submissions.

---

Workflow: Viewing Customer Submissions

When the user asks "who signed up?" or "show me the submissions":

1. Call ListSubmitFormDetail for the relevant form name.
2. Parse each payload field (it's a JSON string) and build a unified table.
3. If there are many fields, ask the user which columns matter most and filter accordingly.
4. For bulk export, suggest the admin panel: https://knowuv.com/admin/internal/form_structure

---

Tips

• Form name consistency: The same name must be used in SubmitForm and ListSubmitFormDetail to link submissions to the right form. A typo creates a new, separate form.
• Pagination: Default to page_size: 20. If total exceeds this, offer to fetch more pages.
• Timestamps: ctime is a Unix timestamp in seconds. Convert to local time when displaying.
• Non-technical language: Users are often business owners, not developers. Say "customer submissions" not "form detail records". Say "registration form" not "SubmitForm endpoint".
• Payload display: Always parse and render the JSON payload as readable key-value pairs or a table — never dump the raw JSON string at the user.