Form Manager

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 = 
USER_TOKEN = 

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

---

Base URL & Request Format

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

All responses:

{ "code": 0, "msg": "...",  }

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\": \"alice@example.com\", \"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": "",
  "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": "",
  "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": "",
  "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": "",
  "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": "" }

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": "" }

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.

1. Test the integration — after the page is live, call GetLatestSubmitFormDetail to

confirm a test submission arrived.

1. 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dusty-cjh
• Source: dusty-cjh/knowuv-skill-set
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.