getUsers()

Prev
This content is currently unavailable in Spanish. You are viewing the default (English) version.

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

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.

fields

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.

sortDir

string

Specifies the sort direction. Possible values are asc (ascending) or desc (descending). By default, the data is sorted by the username field (referred to as name in the API response) in descending order.

limit

number

Limit the number of items returned in the data array.

siteGUID

string

The GUID of the site to which the user belongs. You can retrieve the GUID by using the sites.getSites() method and providing the site name.

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

meta

Object

Object containing status, statusMsg, and request details.

data

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

href

string

Relative URL of the record.

dataType

string

Type of data returned (in this case, a User). Other types of data could be FormTemplate, for example.

id

string

GUID of the user.

passwordExpires

string

The password expiration date in ISO 8601 format.

userIdExpires

string

The User ID expiration date in ISO 8601 format.

siteId

string

The GUID of the site to which the user is associated.

userIdNeverExpires

boolean

Determines if the User ID has an expiration date. (Otherwise the year value will be 9999).

passwordNeverExpires

boolean

Determines if the password has an expiration date. (Otherwise the year value will be 9999).

enabled

boolean

Indicates whether the user has permission to log into the site.

lastIpAddress

boolean

The most recent IP address used by the user to log into the site.

modifyDate

string

The date and time (in ISO 8601 format) when the user’s information was last updated.

isVaultAccess

boolean

Determines if the user is a member of the vaultAccess group.

isVaultAdmin

boolean

Determines if the user is a member of the vaultAdmin group.

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.

Related Methods