Definition

The "List Groups" action allows you to retrieve a list of groups within a specified Google Directory. By using this action, you can easily find groups by their associated details, including email addresses, descriptions, and members. This action is essential for administrators managing large organizations or multiple domains, providing an efficient way to explore and organize groups. Key capabilities include filtering groups by domain, customer ID, user membership, and group names, as well as handling pagination to manage large datasets.

Example Use Cases

1. IT Admin Managing User Groups

An IT administrator needs to list all the groups within a specific domain to manage user access and permissions. By using the "List Groups" action, they can retrieve a comprehensive list of groups, including details like group email, name, and member count, to ensure proper organization.

2. HR Department Organizing Employee Groups

HR teams want to list all the groups in their directory to check the grouping of employees across various departments. Using this action, HR can filter groups by their names or emails and ensure all employees are placed in the correct groups.

3. Auditing Group Membership

A security officer needs to audit groups and confirm that only authorized individuals have membership access to specific groups. By using this action with the user ID filter, they can retrieve all the groups that a particular user is a member of, allowing for a streamlined audit process.

4. Multi-Domain Organization Group Management

In a multi-domain organization, an admin wants to list all groups across various domains. Using the "List Groups" action with the domain or customer ID, they can fetch the groups from all domains to centrally manage access and permissions.

5. Reporting and Data Analysis

A reporting team is gathering information about the number of groups within a domain or organization. By utilizing this action, they can pull data on the number of groups and group attributes, such as the number of direct members, which can be used for internal reporting.

Inputs

1. Connection

The connection to the Google Directory API that allows access to your Google Workspace account.

Explanation: This is where you set up the connection to the Google Directory service. You’ll need valid authentication credentials to connect successfully.

2. Domain

The domain name used to filter the groups.

Explanation: Specify the domain name (e.g., "example.com") to retrieve groups only from that domain. If left empty, groups from all domains may be returned.

3. Customer Id

The unique ID of the customer in Google Admin Console.

Explanation: This ID helps to identify the customer’s account. Use this field instead of domain if you need to fetch all groups for a specific customer. You can also use "my_customer" as a placeholder to refer to your own customer ID.

4. User Id

The email address or immutable ID of a user whose group memberships need to be listed.

Explanation: If provided, this filters the groups based on the user’s membership. Only the groups where this user is a member will be retrieved.

5. Name Prefix

The prefix of the group’s display name.

Explanation: You can filter the groups by specifying the starting characters of the group name. This helps to narrow down the results to specific groups that match the prefix.

6. Email Prefix

The prefix of the group’s email address.

Explanation: Similar to the Name Prefix, you can filter groups by the beginning part of their email address (e.g., “marketing@” for all marketing-related groups).

7. Max Result

The maximum number of groups to return.

Explanation: The value here limits the number of groups that will be fetched. The maximum value is 10,000. This is useful for controlling the amount of data returned at once.

8. Next Page Token

The token to fetch the next page of results.

Explanation: If the number of groups exceeds the maximum limit (e.g., 10,000), the results will be paginated. Use the Next Page Token to retrieve the next set of results. If left blank, the first page of data will be returned.

Outputs

1. Number of Groups

The total number of groups retrieved by the action.

Explanation: This field returns the number of groups that match the query criteria. It provides a quick overview of how many groups are found based on the given input parameters.

2. Group Id

The unique ID of each group.

Explanation: This field provides the unique identifier for each group. The group ID can be used to reference specific groups when making further API requests, such as retrieving group details or updating the group.

3. Group Email

The primary email address of the group.

Explanation: The email address associated with the group, which is typically used to send messages to the entire group.

4. Name

The display name of the group.

Explanation: This field provides the human-readable name of the group, which helps in identifying the group in the directory.

5. Description

The description of the group.

Explanation: This field provides additional details about the group, helping users to understand its purpose or usage.

6. Created by Admin

Indicates whether the group was created by an administrator.

Explanation: This field returns a value of "true" if the group was created by an administrator, or "false" if it was created by a user. It helps in distinguishing groups created by admins versus those created by other members.

7. Direct Members Count

The number of direct members in the group.

Explanation: This field shows how many users are direct members of the group. Note that members of sub-groups (nested groups) are not counted in the direct members count.

8. Aliases

A list of the group’s alias email addresses.

Explanation: This field contains all the aliases that can be used to email the group. Aliases are additional email addresses that forward to the group's primary email.

9. Non-Editable Aliases

A list of non-editable alias email addresses.

Explanation: This field lists alias email addresses that cannot be modified by the admin or the user. These aliases are often external email addresses or system-generated addresses that are tied to the group.

10. Next Page Token

The token to fetch the next page of results.

Explanation: If the results are paginated (i.e., more than the maximum number of results), this token is provided to retrieve the next set of group data. If no more results are available, this field will be empty.

Example Scenario

Scenario: Retrieving All Groups from a Domain for an Admin Dashboard

Use Case: An IT administrator wants to retrieve a list of all groups from their company's Google Workspace domain to display in their internal admin dashboard. The goal is to manage and monitor these groups for access control, collaboration, and reporting purposes.

Steps to Set Up:

1. Input Fields:

   • Connection: The administrator will need to set up a valid connection to the Google Workspace domain through OAuth or API credentials.
   • Domain: The administrator enters the domain name (e.g., example.com) to retrieve groups from that specific domain.
   • Customer Id: The customer ID (e.g., C12345678) will be used if the admin is managing multiple domains or needs to query the groups for a specific customer account in a multi-domain setup.
   • Max Result: The admin can set a value of, say, 500 to retrieve a maximum of 500 group entries per request to manage the load.
   • Next Page Token: If there are more than 500 groups, the next page token will allow the administrator to fetch the next batch of groups.

2. Execution:

   • The admin configures the "List Groups" action in the workflow tool or system, providing the necessary input parameters.
   • When executed, the action will return a paginated list of groups in the specified domain, with details such as the group’s unique ID, email address, name, and description.

3. Outputs:

   • The response will include a list of groups with detailed information: the group ID, email, name, description, number of direct members, and any aliases associated with the groups.
   • If there are more than 500 groups, the Next Page Token will help the admin fetch additional groups.

4. Use Case Example:

   • The admin can now view the groups in a table on the dashboard, filter by group name or email, and easily access more details about any group, such as its members, aliases, or description.
   • For large organizations, this action allows efficient group management, making it easier to monitor and report on group activity across the domain.

This action can be integrated into an internal admin tool, providing real-time insights and streamlining group management processes for the IT team.