getForms()

const params = {
    q: `[First Name] eq 'John'`,
    fields: 'Last Name, Email'
};
 
const res = await vvClient.forms.getForms(params, templateName)

Overview

getForms() is a method in the VisualVault Node.js vvClient wrapper that retrieves form records data and their associated metadata from a specified form template in VisualVault.

Use Cases

Basic Data Retrieval: Find all the records of a form template by providing the form template name.
Filtered Queries: Narrow your search to records matching exact conditions (e.g., status, date ranges, Form ID, etc).

Method Signature

vvClient.forms.getForms(params, templateName)

Parameters

Name	Type	Description
`templateName`	string, required	The exact name of the form template in VisualVault.
`params`	object, required
↳ `q`	string	A query filter string including any OData operator to compare values. Similar to a SQL WHERE clause. For more information, check Query Syntax.
↳ `expand`	boolean	When true, returns the data of all fields of the form.
↳ `fields`	string	A comma-separated list of fields names to return only their data if you don’t want all fields. If a field name does not exists, it will be ignored.

Params Object Example:

const params = {
  q: "[Individual ID] eq '12345'",
  fields: "id, name"
};

Where to Find Template Names
Template names are defined and managed in the VisualVault platform under "/Forms/Form Templates". You’ll need to reference these names exactly as they are defined in the platform when calling getForms. Ensure the template name you use matches one that exists in your environment.

Response

A typical successful response includes:

Name	Type	Description
`meta`	Object	Object containing `status`, `statusMsg`, and request details.
`data`	Array	An array of form record objects. If no records match, data is an empty array.

Response Examples

Records Found:

{
  "meta": {
    "status": 200,
    "statusMsg": "OK",
    "method": "GET",
    "href": "..."
  },
  "data": [
    {
      "business Name": "The Business Name",
      "business Address": "2521 E Market St",
      "instanceName": "BUSINESS-000199",
      "revisionId": "60ade4a6-4d64-ee11-8242-9bf73852412b",
      ...
    },
    {
      "business Name": "Another Business Name",
      "business Address": "45 Busy St",
      "instanceName": "BUSINESS-000200",
      "revisionId": "60ade5gg-223a-34g4-8242-3fh73852001fh",
      ...
    }
  ], ...
}

No Record Found:

{
  "meta": {
    "status": 200,
    "statusMsg": "OK",
    "method": "GET",
    "href": "..."
  },
  "data": []
}

Invalid Template Name:

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

Invalid Field Name in Query:

{
  meta: {
    status: 400,
    statusMsg: "BadRequest",
    method: "GET",
    href: "https://vv5dev.visualvault.com/api/v1/CityofLincoln/Phase2/formtemplates/5e98a19a-afe9-ed11-b97d-0e849d8fa1ab/forms?q=Fake Name eg \"test\"",
    errors: [
      {
        code: null,
        developerMessage: "Invalid expression, invalid column: 'Fake Name', at loc:1",
        message: "Invalid expression, invalid column: 'Fake Name', at loc:1",
        reason: "Query syntax error",
      },
    ],
  },
}

Record Metadata Properties

Regardless of whether you request data for specific fields or all fields, each record object always includes the following metadata:

Name	Type	Description
`createBy`	string	ID of the user who created the record
`createById`	string	GUID of the user who created the record
`createDate`	string	Date when the record was created
`dhid1`	string	Record GUID
`href`	string	Relative URL of the record
`instanceName`	string	Record ID
`modifyBy`	string	ID of the user who last modified the record
`modifyById`	string	GUID of the user who last modified the record
`modifyDate`	string	Date of the record’s last modification
`revisionId`	string	Record GUID

Limitations

Record Limit for getForms() Method
The getForms() method returns a maximum of 200 records, regardless of the query parameters provided.

Performance Considerations

Large Datasets Or High Traffic Microservices

If you need to handle large datasets (e.g., more than 200 records) or you are working in a microservice that will have a high demand consider the following approaches:

Limit the amount of returned records by filtering by the specific criteria of your use case.
Use the fields property of the params object to return only the field values you need.
Create a q filter string to limit the number of returned records to a fixed amount and run getForms() to get the records in batches.
Implement a semaphore algorithm.
Use getCustomQueryResultsByName.

Best Practices

Be Specific with Queries: Define q filters to narrow down results and save bandwidth.
Use Fields or Expand: If you only need a handful of fields, specify them to speed up responses. If you need everything, use expand: true.
Always Validate: Apply validation functions after each call to ensure data integrity.
Know the Limits: Switch to getCustomQueryResultsByName for queries that requires dynamic SQL parameters or when dealing with more than 200 records.