postForms()

const data = {
    'First Name': 'John',
    'Last Name': 'Doe',
};
const formTemplateId = 'Template Name'; // you can use the template GUID instead

const res = await vvClient.forms.postForms(null, data, formTemplateId);

Overview

postForms() is a method in the VisualVault Node.js vvClient wrapper that enables the creation of a new form record associated with a specific form template.

Use Cases

Single Record Creation: Create a single record using a predefined form template.
Batch Record Creation: Utilize additional methods to generate multiple records by importing data from an external source, such as a CSV file.

Method Signature

vvClient.forms.postForms(null, data, formTemplateId)

Parameters

Name	Type	Description
`params`	object	This parameter does not affect the functionality of this method and is typically set to `null`.
`data`	object, required	An object containing the field data for the new record, where each `key` represents a field name and its corresponding `value` represents the field’s content.
`formTemplateId`	string, required	The name of the form template used to create the form record. This can also be specified as a GUID.

Response

A typical successful response includes:

Name	Type	Description
`meta`	object	Object containing `status`, `statusMsg`, and request details.
`data`	object	An object containing metadata associated with the newly created record.

Response Examples

Record Created:

{
  meta: {
    status: 201,
    statusMsg: "Created",
    method: "POST",
    href: "...",
  },
  data: {
    href: "...",
    dataType: "FormInstance",
    revisionId: "...", //guid
    instanceName: "INSTNAME-0001",
    modifyDate: "2025-01-13T19:31:26.07Z",
    modifyById: "...", //guid
    modifyBy: "username",
    createDate: "2025-01-13T19:31:26.07Z",
    createById: "...", //guid
    createBy: "username",
  },
}

Invalid Template Name:

{"message": "The request is invalid."}

Double-check Field Names
Ensure that the fields provided in the data object match the field names defined in the form template. This method will not throw an error if the field names are incorrect, so validation is essential.

Record Metadata

This data is returned once the record has been successfully created.

Name	Type	Description
`href`	string	Relative URL of the record.
`dataType`	string	Type of data created (in this case, a form instance).
`revisionId`	string	GUID of the form record revision ID.
`instanceName`	string	ID of the form record.
`modifyDate`	string	Date time when the record was last modified.
`modifyById`	string	GUID of the user modifying the record.
`modifyBy`	string	Username of the user that modified the record.
`createDate`	string	Date time when the record was created.
`createById`	string	GUID of the user that created the record.
`createBy`	string	Username of the user that created the record.

Best Practices

Prefer Using IDs Over GUIDs: Use the ID (form template name) to identify the template instead of the GUID (hexadecimal component identifier). Unlike GUIDs, which can vary between environments, IDs remain consistent.
Database Propagation Delay: Updating or relating a form record immediately after creation may fail due to propagation delays. Use setTimeout() to wait or handle relationships in a second phase after finishing all the records creation.
Required Fields: Validate required fields before using this method. If omitted, postForms() will still create the record but leave the fields blank.
Performance Considerations: High volumes of rapid network requests can degrade performance or cause server failures. Optimize your script accordingly.

Related Methods

postFormRevision()