List Users
Definition
The "List Users" action retrieves and lists users from the Google Directory based on various filters and search criteria. This action allows administrators to search for users by name, email, title, organization, department, or other attributes. It can fetch either administrator-only or domain-wide public views of users and supports pagination for large datasets.
Key Capabilities:
- Search Users by Specific Criteria: Filter users by domain, name, email, job title, manager, organization, department, or custom query.
- Retrieve User Details: Get information on active, suspended, or administrator users.
- Support for Pagination: Retrieve up to 10,000 users per request and use pagination for large directories.
- Flexible Querying: Use Google’s search query parameters to refine the search results efficiently.
Example Use Cases
1. Fetch All Users in an Organization
Retrieve a list of all users in a specific domain or customer account for administrative or auditing purposes.
2. Find a User by Name or Email
Quickly search for a specific user by their full name, primary email, or alias to check their details or status.
3. Identify Suspended Users
List all suspended users in the directory to review and reinstate accounts if needed.
4. Retrieve Users by Department or Organization
Filter users by department (e.g., IT, HR, Sales) or organizational unit to manage department-specific policies or reports.
5. Find Users Under a Specific Manager
List all employees reporting to a specific manager by searching for users based on their manager’s email.
6. Audit Super Admins
Retrieve a list of all super administrators in the domain to verify account security and role assignments.
7. Paginate Through Large User Lists
Fetch users in batches using pagination when handling large organizations with thousands of employees.
Inputs Explanation
1. Connection
The authorization connection to Google Directory. This must have the necessary permissions to search and list users in the organization.
2. Information to Return
Specifies whether to retrieve administrator-only or domain-wide public view of the user data.
3. Domain
The domain name to filter users from a specific domain. If you want to list users from all domains under a customer account, use the Customer ID field instead.
4. Name or Email
Allows searching for users by:
- Full name (concatenated first and last name).
- Email addresses (including aliases).
5. Title
Filters users based on their job title (e.g., "Software Engineer", "HR Manager").
6. Manager
Search for users based on their direct manager’s email. This can be used to find all employees under a specific manager.
7. Parent Org Path
Defines the organizational unit path the user belongs to. For example:
- "/IT/Developers" for employees under the IT department's Developer group.
- "/HR" for HR department employees.
8. Organization
Filters users based on their assigned organization (company name, entity, or division).
9. Department
Allows searching for users based on their department (e.g., "Finance", "Marketing").
10. Customer ID
The unique identifier of the customer account. If your organization has multiple domains, this ensures you fetch users across all domains.
- You can also use the alias "my_customer" to refer to your own customer account.
11. Query
A custom search query to filter users based on various attributes. Example query formats:
name:John
→ Find users with "John" in their name.isSuspended=true
→ List only suspended users.[email protected]
→ Find users reporting to a specific manager.
Google’s query documentation provides more details.
12. Admin
Set to true to retrieve only users with super administrator privileges in the Google Directory.
13. Suspended
Filter users based on suspension status:
- true → Retrieve only suspended users.
- false → Retrieve only active users.
14. Direct Manager
Fetches users who have a direct reporting manager assigned.
15. Max Results
Defines the maximum number of users returned in the result.
- The value can be between 1 and 10,000.
- If there are more results than the limit, use Next Page Token to fetch additional results.
16. Next Page Token
Used for pagination when fetching large numbers of users. If more users are available beyond the max results limit, this token helps retrieve the next set of users.
**Outputs **
1. Number of Users
This represents the total count of users returned by the query, based on the input search parameters. It helps in understanding how many users match the specified search criteria.
2. Next Page Token
This is a token that helps retrieve the next set of results when there are more users than the maximum results per page limit.
- If the result set exceeds the max results limit, this token should be used to fetch the next page of users.
- The presence of a next page token indicates that additional pages of data are available for retrieval.
3. Users List
This contains the complete list of users matching the query criteria. Each user in the list includes comprehensive user data, such as their personal details, organizational unit, group memberships, role/privileges, email, and other attributes.
- For details on the exact data provided for each user, refer to the separate document , which explains the complete structure of the returned user data.
Detailed User information (Output)
These outputs allow you to assess how many users matched your search and whether you need to paginate to retrieve the full list. The user list will give you all relevant data on each user in your organization.
**Example of Using **
Scenario:
A Google Workspace admin wants to retrieve a list of all active users in the company who are part of the "Engineering" department to ensure they have the correct roles and access.
Steps:
-
Input:
- Connection: Admin has a valid Google Directory connection.
- Domain: The admin specifies the company domain to limit the results to this domain.
- Department: The admin sets the department filter to "Engineering" to search only users in this department.
- Suspended: The admin selects "No" to exclude suspended users from the results.
- Max Results: Set to 100 to limit the number of results displayed on one page.
-
Execution:
The action queries the directory and returns a list of all active users who are in the "Engineering" department. -
Output:
- The number of users returned will be displayed (e.g., 15 users).
- If there are more than 100 users, a next page token will be provided to fetch the next batch of results.
- A detailed user list will be returned with attributes like name, email, job title, and organizational unit.
Outcome:
The admin can now review the list of users in the Engineering department, verify their details, check their roles, and ensure all users have the proper access to the tools and resources needed for their work.
Updated 3 days ago