Get a group id by group name

Tool Name: airdroid_business_get_group_id_by_group_name

Risk Level: 🟢 Low Risk

Execution Mode: ⚡ Synchronous

Category: Group Management

Quick Start (Copy & Use)

One-liner: Look up the GroupId by exact group name match for subsequent group operations.

You need: GroupName (group name, exact match, case-sensitive)

Success criteria: StatusCode == 200 AND ErrorMessage == "" AND GroupIds array is not empty

What to do next: Use the returned GroupId with Get a Group, Move Devices to a Group, or other tools that require a GroupId

Minimum request example:

{
  "GroupName": "Sales Team"
}

Minimum response example:

{
  "GroupIds": [24535],
  "StatusCode": 200,
  "ErrorMessage": ""
}

Recipes (Common Recipes)

Recipe 1: Look up a group's ID

Scenario: Get the ID of a group by its name

{
  "GroupName": "Sales Team"
}

Recipe 2: Look up the default group's ID

Scenario: Get the ID of the enterprise's default group (each enterprise has exactly one)

{
  "GroupName": "Default"
}

Note: The default group name is always "Default" (case-sensitive).

Recipe 3: Look up then get group details

Scenario: Get full group information by group name

Step 1: Call this tool to get the GroupId

{
  "GroupName": "Sales Team"
}

Step 2: Use the returned GroupId to call Get a Group

{
  "GroupId": 24535
}

1. Overview

1.1 Description

Look up a group ID in AirDroid Business by exact group name match. This is a commonly used helper tool that converts user-provided group names to system-internal GroupIds for calling other tools that require the GroupId parameter.

1.2 When to Use

• Name to ID conversion: User provides a group name, but subsequent operations require a GroupId
• Verify group existence: Check whether a group with a specific name exists
• Create nested groups: Get the parent group ID for the ParentGroupId parameter of Create a Group
• Move devices to a group: Get the target group ID for the Move Devices to a Group operation

1.3 Execution Mode & Response

This is a synchronous operation that returns the GroupId list immediately.

• Return value: GroupIds array (integer array)
• Typical latency: < 1 second

1.4 Prerequisites

1.5 Prerequisite Tools

No direct dependencies. This tool is typically used as a prerequisite for other tools.

1.6 Comparison with Similar Tools

2. Inputs

2.1 Parameter List

2.2 Parameter Details

`GroupName`

The group name to query, using exact match.

• Type: string
• Format requirements:
  • Cannot be empty or contain only spaces
  • Exact match, case-sensitive
  • Default group name is "Default"
• Source: User-provided or obtained from a business system
• How to fill in a GI node:
  • Constant value: Enter a string directly, e.g. "Sales Team"
  • Upstream output reference: Get the group name field from an upstream node
• Example:

"Sales Team"

Important notes:

• Name matching is exact match; "sales team" and "Sales Team" are different
• If duplicate-named groups exist (not recommended), multiple GroupIds will be returned

3. Outputs

3.1 Response Examples

Success response (group found):

{
  "GroupIds": [24535],
  "StatusCode": 200,
  "ErrorMessage": ""
}

Success response (group not found):

{
  "GroupIds": [],
  "StatusCode": 200,
  "ErrorMessage": ""
}

Success response (duplicate group names):

{
  "GroupIds": [24535, 24536],
  "StatusCode": 200,
  "ErrorMessage": ""
}

Error response (parameter error):

{
  "GroupIds": [],
  "StatusCode": 200,
  "ErrorMessage": "Invalid group_name."
}

3.2 Field Descriptions

3.3 GroupIds Return Value Explanation

4. Examples

4.1 Basic Example: Look up a group ID

Request parameters:

{
  "GroupName": "Sales Team"
}

Response:

{
  "GroupIds": [24535],
  "StatusCode": 200,
  "ErrorMessage": ""
}

4.2 Advanced Example: Look up the default group

Request parameters:

{
  "GroupName": "Default"
}

Response:

{
  "GroupIds": [1],
  "StatusCode": 200,
  "ErrorMessage": ""
}

4.3 Error Example: Group not found

Request parameters:

{
  "GroupName": "Non Existent Group"
}

Response:

{
  "GroupIds": [],
  "StatusCode": 200,
  "ErrorMessage": ""
}

Agent handling advice: An empty GroupIds array means the group does not exist. Prompt the user to check the group name spelling or create a new group.

5. Error Handling

5.1 AB Three-Layer Error Codes

Core principle: AB uses a three-layer error code strategy. The Agent should decide its handling approach based on the StatusCode.

5.2 Common Errors

5.3 Agent Self-Healing Decision Table

6. Best Practices

6.1 Performance Optimization

• Cache results: Group IDs rarely change; cache query results for reuse
• Avoid redundant queries: Within the same workflow, store the GroupId in a variable for reuse

6.2 Security Considerations

🟢 Read operation: No special security concerns; this operation does not modify any data.

6.3 Name Matching Notes

• Exact match: Name must match exactly, including case and spaces
• Default group: The system default group name is "Default"
• Duplicate names: Although not recommended, the system allows creating groups with duplicate names; in that case, multiple IDs will be returned

7. Related Tools

7.1 Prerequisite Tools

No direct dependencies. This tool is typically used as a prerequisite step for other tools.

7.2 Follow-up Tools

7.3 Similar Tools Comparison

8. Tool Chains

8.1 Name to ID Then Get Group Details

Scenario: User provides a group name; need to retrieve full group information

Tool chain:

Get a Group ID by Group Name → Get a Group

Steps:

1. Call Get a Group ID by Group Name with the group name
2. Check that GroupIds is not empty
3. Use GroupIds[0] to call Get a Group for details

8.2 Create Nested Groups

Scenario: Create a sub-group under an existing group

Tool chain:

Get a Group ID by Group Name → Create a Group

Steps:

1. Call Get a Group ID by Group Name to get the parent group ID
2. Use the returned GroupId as ParentGroupId
3. Call Create a Group to create the sub-group

8.3 Move Devices to a Named Group

Scenario: User provides a target group name; need to move devices into that group

Tool chain:

Get a Group ID by Group Name → Move Devices to a Group

Steps:

1. Call Get a Group ID by Group Name to get the target group ID
2. Verify the group exists (GroupIds is not empty)
3. Use the GroupId to call Move Devices to a Group

8.4 Verify Group Exists Before Deleting

Scenario: Safely confirm the group exists before deleting

Tool chain:

Get a Group ID by Group Name → Delete Groups

Steps:

1. Call Get a Group ID by Group Name to confirm the group exists
2. If GroupIds is empty, inform the user the group does not exist
3. If it exists, use GroupIds to call Delete Groups (requires user confirmation)