postFormRevision()

const data = {
    fieldName1: 'fieldValue',
    fieldName2: 'fieldValue',
};
const formTemplateId = "Template Name";
const formId = "Record GUID";

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

Overview

postFormRevision() is a VisualVault Node.js vvClient wrapper method that updates an existing form record with new data, creating a new instance of the same form record.

Use Cases

Update a Form Record: Update the information in an existing form record.

Method Signature

vvClient.forms.postFormRevision(params, data, formTemplateId, formId)

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 fields values to update, 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 associated to the record to update. This can also be specified as a GUID.
`formId`	string, required	GUID of the form record to update.

Data Object Example

const data = {
    "First Name": 'John Doe',
    "Start Date": new Date(),
};

Response

A typical successful response includes:

Name	Type	Description
`meta`	Object	Object containing `status`, `statusMsg`, and request details.
`data`	Object	Object containing the updated form record information.

Response Examples

Record Updated:

{
  meta: {
    status: 201,
    statusMsg: "Created",
    method: "POST",
    href: "...",
  },
  data: {
    href: "...",
    dataType: "FormInstance",
    instanceName: "BUSINESS-000035",
    revisionId: "6323a6ea-c4d1-ef11-aa76-b29e86afadab",
  },
}

Record Not Found:

{
  meta: {
    status: 404,
    statusMsg: "NotFound",
    method: "POST",
    href: "...",
    errors: [
      {
        code: null,
        developerMessage: "Resource does not exist",
        message: "Resource does not exist",
        reason: "Resource not found error",
      },
    ],
  },
}

Invalid Template Name:

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

Missing Data Parameter:

{
  meta: {
    status: 500,
    statusMsg: "InternalServerError",
    method: "POST",
    href: "...",
    errors: [
      {
        code: null,
        developerMessage: "Object reference not set to an instance of an object.",
        message: "An error on the server has occurred",
        reason: "Server exception occurred",
      },
    ],
  },
}

Record Metadata Properties

Each returned record object always includes the following metadata:

Name	Type	Description
`href`	string	Relative URL of the record
`dataType`	string	The data type of the new instance created
`instanceName`	string	Record ID
`revisionId`	string	Record GUID

Performance Considerations

Minimize Server Load:

To reduce server strain, send only the field values that need to be updated. Avoid including unchanged field values in the request.

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 a form record immediately after creation or update may fail due to propagation delays. Use setTimeout() to wait or handle updates in a second phase after finishing all the initial processing.

Related Methods

postForms()