const params = {
q: `[userid] eq 'johndoe@visualvault.com'`,
fields: 'id, name, userid, siteid, firstname, lastname, emailaddress',
sortDir: "asc",
limit: 10
};
const siteGUID = "Site GUID";
const res = await vvClient.users.getUsers(params, siteGUID)
Overview
getUsers()
is a method in the VisualVault Node.js vvClient wrapper that retrieves data from multiple users, and their associated metadata for a given site.
Clarification: getUsers() vs getUser()
getUsers()
: This method retrieves up to 200 users within a specific site. It is scoped to the site provided in the query, making it ideal for operations limited to a single site.
getUser()
: This method retrieves user data across all sites, regardless of the specific site context. Use this when you need information about a user globally, not tied to a particular site.
Use Cases
Find information about a single user: Obtain data for a specific user in a site by including the
q
parameter.Find all users in a site: Retrieves data for up to 200 users in a site.
Perform operations on user objects: Use the returned user data with the vvClient wrapper library to perform additional operations—such as enabling or disabling multiple users in bulk.
Method Signature
vvClient.users.getUsers(params, siteGUID)
Parameters
Name | Type | Description |
---|---|---|
| object, required | |
↳ | string | A query filter string including any OData operator to compare values. Similar to a SQL WHERE clause. For more information, check Query Syntax. |
↳ | string | A comma-separated list of field names to specify which fields or columns should be included in the response. If a field name does not exist, it will be ignored. |
↳ | string | Specifies the sort direction. Possible values are |
↳ | number | Limit the number of items returned in the data array. |
| string | The GUID of the site to which the user belongs. You can retrieve the GUID by using the |
Params Object Example:
const params = {
q: `emailaddress LIKE '%@visualvault.com'`,
fields: 'id, name, userid, siteid, firstname, lastname, emailaddress',
sortDir: "asc",
limit: 100
};
Response
A typical successful response includes:
Name | Type | Description |
---|---|---|
| Object | Object containing |
| Array | An array of user objects. If no user matches the parameters, data is an empty array. |
Response Examples
Users Found:
"meta": {
"status": 200,
"statusMsg": "OK",
"method": "GET",
"href": "..."
},
"data": [
{
href: "~/sites/24d8d995-936b-480b-99cf-696ec5f34412/users/23770ac1-21fe-4b73-a312-91cc2ed33562",
dataType: "User",
id: "23770ac1-21fe-4b73-a312-91cc2ed33562",
name: "john_doe",
userid: "john_doe",
firstName: "John",
middleInitial: "",
lastName: "Doe",
passwordExpires: "2025-12-31T00:00:00Z",
userIdExpires: "9999-12-31T00:00:00Z",
emailAddress: "john.doe@email.com",
siteId: "24d8d995-936b-480b-99cf-696ec5f34412",
userIdNeverExpires: true,
passwordNeverExpires: false,
enabled: true,
lastIpAddress: "",
modifyDate: "2024-11-13T13:57:30.51Z",
isVaultAccess: false,
isVaultAdmin: false,
}
],
}
No Users Found Or Incorrect Site GUID:
{
"meta": {
"status": 200,
"statusMsg": "OK",
"method": "GET",
"href": "..."
},
"data": []
}
Missing GUID parameter
{message: 'The request is invalid.'}
Invalid Field Name in Query:
{
"meta": {
"status": 400,
"statusMsg": "BadRequest",
"method": "GET",
"href": "...",
"errors": [
{
"code": null,
"developerMessage": "Invalid expression, invalid column: 'badcol', at loc:0",
"message": "Invalid expression, invalid column: 'badcol', at loc:0",
"reason": "Query syntax error"
}
]
}
}
User 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 |
---|---|---|
| string | Relative URL of the record. |
| string | Type of data returned (in this case, a User). Other types of data could be FormTemplate, for example. |
| string | GUID of the user. |
| string | The password expiration date in ISO 8601 format. |
| string | The User ID expiration date in ISO 8601 format. |
| string | The GUID of the site to which the user is associated. |
| boolean | Determines if the User ID has an expiration date. (Otherwise the year value will be 9999). |
| boolean | Determines if the password has an expiration date. (Otherwise the year value will be 9999). |
| boolean | Indicates whether the user has permission to log into the site. |
| boolean | The most recent IP address used by the user to log into the site. |
| string | The date and time (in ISO 8601 format) when the user’s information was last updated. |
| boolean | Determines if the user is a member of the |
| boolean | Determines if the user is a member of the |
Limitations
User Limit In Response: The
getUsers()
method can return a maximum of 200 users per request, regardless of the query parameters provided.Site User Limit: Each site has a configured user limit, typically set to 2,000 users. If you’re unsure of the specific limit, consult the site administrator.
Best Practices
Clean up names and emails: Remove any leading or trailing spaces and escape apostrophes to ensure more accurate query results.
Retrieve only active users: Unless otherwise required by your logic, filter for enabled users to exclude data for users who are no longer active.