Skip to content

k.site.formValues ​

Query, create, update, and delete form submission records (FormValue)

Execution ContextPrerequisitesTypical Use
KScript API / Server scriptsCurrent site context; adding records requires a target formIdRead, store, update, and delete site FormValue submissions

Quick Start ​

Create a base record with add({ name, formId }), retrieve it from all(), assign keys on values, and persist with update():

js
k.api.post(() => {
    const name = "submission-" + Date.now()
    const formId = k.request.form.formId

    k.site.formValues.add({ name, formId })
    const created = k.site.formValues.all().find((x) => x.name === name)
    created.values["email"] = k.request.form.email
    created.values["topic"] = k.request.form.topic
    k.site.formValues.update(created)

    const saved = k.site.formValues.get(created.id)
    return { id: String(saved.id), values: saved.values }
})

Quick Reference ​

Method / PropertyDescriptionReturns
all()Returns all stored form submission recordsFormValue[]
get(nameOrId)Retrieves a form submission record by GUID idFormValue | null
add(formValue)Creates a base submission record (avoid nested values here)void
update(formValue)Persists changes to values and record metadatavoid
delete(nameOrId)Deletes a form submission record by idvoid
getLogs(nameOrId)Returns null because form values do not keep change logsChangeLog[] | null
getByLog(logId)Restores a log version when availableFormValue | null

Runtime Notes

  • Do not pass a nested values object directly to k.site.formValues.add({ name, formId, values: { ... } }), which throws a type-conversion error when binding nested fields. Instead, create the record with add({ name, formId }), retrieve it from all(), assign entries on item.values["field"], and call update(item).
  • FormValue generates a random GUID id; use that id with get(id) and delete(id).
  • Form submissions are not versioned in the change log; getLogs(id) returns null.

Detailed Methods ​

all() / get() ​

List all form submission records or retrieve one by its GUID id.

MethodParametersReturnsDescription
all()NoneFormValue[]Returns all stored form submission records
get(nameOrId)nameOrId: stringFormValue | nullRetrieves a form submission record by id

Returns: FormValue[] or FormValue | null

js
k.api.get(() => {
    const items = k.site.formValues.all()
    return {
        count: items.length,
        latest: items.slice(0, 5).map((item) => ({
            id: String(item.id),
            name: item.name,
            formId: String(item.formId),
            values: item.values
        }))
    }
})

add() and update() ​

Create the base record first, populate values, and persist via update().

ParameterTypeRequiredDescription
formValue{ name?: string; formId: string } / FormValueYesPass name and formId to add(); assign values entries then pass to update()

Returns: void

js
k.api.post(() => {
    const item = k.site.formValues.get(k.request.form.id)
    if (!item) return { found: false }
    item.values["status"] = "reviewed"
    k.site.formValues.update(item)
    return { updated: true }
})

delete() and getLogs() ​

Delete a submission by id or check log behavior.

MethodParametersReturnsDescription
delete(nameOrId)nameOrId: stringvoidDeletes the form submission record by id
getLogs(nameOrId)nameOrId: stringChangeLog[] | nullReturns null because form values do not store repository change logs
getByLog(logId)logId: numberFormValue | nullLooks up a log version when available

Returns: void / ChangeLog[] | null / FormValue | null

js
k.api.post(() => {
    const id = k.request.form.id
    k.site.formValues.delete(id)
    return { deleted: !k.site.formValues.get(id) }
})

TypeScript Definitions ​

ts
interface FormValuesRepository {
  all(): FormValue[];
  get(nameOrId: string): FormValue | null;
  add(formValue: { name?: string; formId: string }): void;
  update(formValue: FormValue): void;
  delete(nameOrId: string): void;
  getLogs(nameOrId: string): ChangeLog[] | null;
  getByLog(logId: number): FormValue | null;
}

interface FormValue {
  id: string;
  formId: string;
  name: string;
  values: Record<string, string>;
  creationDate: Date;
  lastModified: Date;
  lastModifyTick: number;
}