listUsers Documentation

Purpose

This node interact with Slack's API to retrieve a list of users belonging to a specific team. This function fetches user details based on provided parameters such as team ID and pagination controls. It serves as a crucial utility for applications needing to manage or interact with user data within a Slack workspace, enabling further integrations, analytics, or user management tasks.

Settings

Setting: teamId

• Input Type: String
• Description: This setting allows you to specify the Slack team ID for which you want to retrieve the user list. If not provided in the input, it defaults to the team ID defined in the configuration.
• Default Value: null (will fallback to the configuration value)

Setting: limit

• Input Type: Numeric
• Description: The limit defines the maximum number of users to retrieve in a single API call. Adjusting this value allows for pagination control; setting a lower limit can reduce response time for large teams, while a higher limit enables bulk data retrieval.
• Default Value: 200

Setting: cursor

• Input Type: String
• Description: This optional setting is used for pagination. If the retrieved user list exceeds the set limit, this cursor indicates where to start fetching subsequent data. Users should supply this value to continue fetching users from where the last call ended.
• Default Value: null (no cursor for the initial request)

How It Works

1. Input Handling: The function begins by initializing teamId, limit, and cursor from the provided inputs or from defaults in the configuration if not supplied.
2. Connection Establishment: It utilizes the utility function the integration connection to establish a connection to the Slack API. This function is provided with the connection type "slack" and the current context.
3. API Call: After a successful connection, it invokes the listUsers method from the Slack integration object. This method passes the confirmed parameters (teamId, limit, and cursor) to retrieve the user data.
4. Error Handling: If any errors occur during data fetching, a structured error message is returned with details regarding the internal failure.
5. Output: Upon successful retrieval of user data, the output is returned in an object with the key output1, containing the user data.

Data Expectations

• The node expects the following input parameters:
  • teamId (string): The unique identifier for the Slack workspace.
  • limit (numeric): The cap on the number of users to return.
  • cursor (string, optional): A pagination token for traversing large sets of user data.

The response data will adhere to the format provided by the Slack API, typically including user identifiers, names, and other relevant user metadata.

AI Integrations & Billing Impact

• AI Integrations: Currently, there are no direct AI integrations associated with this node. However, potential integrations can be established downstream, using this data to implement AI-driven functionalities such as user sentiment analysis.
• Billing Impact: This operation may incur costs based on API usage depending on the pricing tier of the Slack API. Frequent calls to list users, especially for large organizations with numerous users, may lead to increased billing. It is advisable to monitor API quotas and rate limits set by the Slack API to prevent unexpected charges.

Use Cases & Examples

Use Case 1: Team Directory Management

A company may want to build a directory application that lists all users in their Slack workspace, providing quick access to team members' contact details and roles.

Use Case 2: Analytics on User Activity

An analytics platform can utilize the listUsers method to fetch user data that can help analyze engagement rates, determine active users, or assess team structures for reporting purposes.

Use Case 3: Slack User Synchronization

A HR management system needs to sync its internal user database with Slack to ensure that data is consistent across platforms.

Example Configuration for Use Case 1: Team Directory Management

Here is a sample configuration for retrieving user data for a team directory:

{
  "inputs": {
    "teamId": "T012345678",
    "limit": 100,
    "cursor": null
  },
  "config": {
    "teamId": "T012345678",
    "limit": 200,
    "cursor": null
  }
}

In this example, the settings allow for up to 100 users to be fetched at once from the specified Slack team. If the team has more than 100 users, additional calls can be made using pagination with the cursor returned from the initial call.

This structured documentation provides a comprehensive overview of this node, ensuring users can fully leverage its capabilities within the Vantage analytics platform.