List Policy and Kiosk Configurations

Tool Name: airdroid_business_policy_kiosk_configuration_list

Risk Level: 🟢 Low Risk

Execution Mode: ⚡ Synchronous

Category: Policy & Kiosk Configuration

Quick Start (Copy & Use)

Summary: List Policy and Kiosk configurations in the account with pagination, optional name filtering (case-insensitive substring), and sorting. The list mixes Policy and Kiosk rows — distinguish them by base_setting.type.

Prerequisites: A valid OAuth2 AccessToken configured in the GI node Credential. All inputs are optional.

Success Criteria: StatusCode == 200 and ErrorMessage == "".

What to Do Next: Take Configs[].base_setting.config_id and pass it to Get a Configuration (full settings) or Get Config File Deployment Status (per-device deployment status).

Minimal Request Example (recommended to copy directly):

{
  "PageIndex": 1,
  "PageSize": 50,
  "Name": "",
  "Order": "create_time",
  "Ascending": false
}

Minimal Response Example:

{
  "Configs": [
    {
      "base_setting": {
        "config_id": 10023,
        "config_name": "Retail Kiosk EU",
        "type": "Kiosk",
        "platform_type": "Android",
        "status": "On",
        "limit_status": "Effective",
        "config_password": "",
        "relative_setting_id": 0,
        "create_time": "2025-11-03 09:12:45",
        "update_time": "2026-05-20 14:30:02"
      }
    }
  ],
  "Pagination": {
    "total": 1,
    "page_size": 50,
    "page_index": 1,
    "last_page": 1
  },
  "Hint": "",
  "Retryable": false,
  "OriginalStatusCode": 200,
  "StatusCode": 200,
  "ErrorMessage": ""
}

Recipes (Common Recipes)

Recipe 1: List All Configurations (First Page)

When to use: Browse the account's configuration inventory.

{
  "PageIndex": 1,
  "PageSize": 50,
  "Name": "",
  "Order": "create_time",
  "Ascending": false
}

Recipe 2: Search Configurations by Name Keyword

When to use: Resolve a configuration name to its config_id before calling Get a Configuration or apply flows. Matching is a case-insensitive substring match against base_setting.config_name.

{
  "PageIndex": 1,
  "PageSize": 50,
  "Name": "Retail Kiosk",
  "Order": "create_time",
  "Ascending": false
}

Recipe 3: Most Recently Updated First

When to use: Audit which configurations changed recently.

{
  "PageIndex": 1,
  "PageSize": 20,
  "Name": "",
  "Order": "update_time",
  "Ascending": false
}

Recipe 4: Paginate Through All Pages

When to use: Iterate the full inventory. After each call, if Pagination.page_index < Pagination.last_page, call again with PageIndex + 1.

{
  "PageIndex": 2,
  "PageSize": 50,
  "Name": "",
  "Order": "config_name",
  "Ascending": true
}

1. Overview

1.1 Description

Retrieve a paginated list of Policy and Kiosk configurations with:

• Optional name keyword filtering (case-insensitive substring on base_setting.config_name)
• Sorting by config_name, create_time, or update_time in ascending or descending order
• Mixed list: Policy and Kiosk configurations are returned together. There is no input type filter — distinguish rows by the returned base_setting.type (Policy | Kiosk | Windows Policy)

1.2 When to Use

• Browse inventory: See what Policy/Kiosk configurations exist in the account
• Resolve name → config_id: Search by partial name before using a configuration Id elsewhere
• Audit changes: Sort by update_time descending to find recently modified configurations
• Prepare apply/update/replicate flows: List existing configurations first

Don't use when:

• You already have the configuration Id and need full settings — use Get a Configuration
• You need per-device deployment progress — use Get Config File Deployment Status
• You need to create or update a configuration — this tool is list-only

1.3 Execution Mode and Response

This operation is synchronous and returns:

• Configs: Array of configuration objects (each with base_setting and optional child settings)
• Pagination: Pagination metadata (total, page_size, page_index, last_page)
• StatusCode / ErrorMessage / Hint / Retryable / OriginalStatusCode: Call status and error information

1.4 Prerequisites

1.5 Differences from Similar Tools

2. Inputs

2.1 Parameter List

2.2 Parameter Details

`PageIndex`

• Type: number
• Format: Positive integer starting from 1. Values < 1 return StatusCode = -1
• Example: 1

`PageSize`

• Type: number
• Format: Integer 1-50. Values outside this range return StatusCode = -1 (Invalid page_size. Must be between 1 and 50.)
• Example: 50
• Why recommended: Set explicitly to control response size; each config row can include large nested settings objects.

> The GI node prefills 50. The accepted runtime range is 1-50; values above 50 return StatusCode = -1.

`Name`

• Type: string
• Format: Keyword up to 200 characters (longer returns StatusCode = -1). Performs a case-insensitive substring match against base_setting.config_name. Empty string = no filter
• Example: "Retail Kiosk"
• Why recommended: Narrow the result set before paginating; there is no type filter, so a good name convention plus this keyword is the main way to scope results.

`Order`

• Type: string
• Allowed values (whitelist; any other value returns StatusCode = -1):
  • config_name — sort alphabetically by configuration name
  • create_time — sort by configuration creation time
  • update_time — sort by last update time
• Default: create_time
• Example: "update_time"

`Ascending`

• Type: bool
• Values: true = ascending (A to Z, 0 to 9, oldest to newest); false = descending (Z to A, 9 to 0, newest to oldest)
• Default: false
• Example: false

> Use Order (field name) and Ascending (boolean) for sorting. Sort and SortType are not valid inputs.

2.3 Parameter Combination Logic

• All parameters are optional and combine as AND: the name filter is applied first, then sorting, then pagination.
• Pagination.total reflects the count after the Name filter.

3. Outputs

3.1 Response Example

Success response:

{
  "Configs": [
    {
      "base_setting": {
        "config_id": 10023,
        "account_id": 8001234,
        "config_name": "Retail Kiosk EU",
        "config_remark": "Kiosk config for EU retail tablets",
        "type": "Kiosk",
        "platform_type": "Android",
        "status": "On",
        "limit_status": "Effective",
        "config_password": "2580",
        "relative_setting_id": 0,
        "create_time": "2025-11-03 09:12:45",
        "update_time": "2026-05-20 14:30:02"
      },
      "brand_setting": {
        "brand_id": 501,
        "brand_name": "Contoso Retail"
      }
    },
    {
      "base_setting": {
        "config_id": 10031,
        "account_id": 8001234,
        "config_name": "Warehouse Policy",
        "config_remark": "",
        "type": "Policy",
        "platform_type": "Android",
        "status": "On",
        "limit_status": "Effective",
        "config_password": "",
        "relative_setting_id": 0,
        "create_time": "2026-01-12 11:05:00",
        "update_time": "2026-04-02 16:44:10"
      },
      "policy_config_file_setting": {
        "allow_ctl_alarm_volume": 1
      }
    }
  ],
  "Pagination": {
    "total": 2,
    "page_size": 50,
    "page_index": 1,
    "last_page": 1
  },
  "Hint": "",
  "Retryable": false,
  "OriginalStatusCode": 200,
  "StatusCode": 200,
  "ErrorMessage": ""
}

Error response (invalid Order):

{
  "Configs": [],
  "Pagination": {},
  "Hint": "Set Order to config_name, create_time, or update_time, then retry.",
  "Retryable": false,
  "OriginalStatusCode": 0,
  "StatusCode": -1,
  "ErrorMessage": "Invalid Order. Allowed values: config_name, create_time, update_time."
}

3.2 Field Descriptions

3.3 Status Code / Enum Value Mapping

3.4 Pagination

Paging strategy:

• When page_index < last_page, call again with PageIndex + 1
• Use Name to narrow the result set before paginating
• PageSize range is 1-50

4. Examples

4.1 Basic Example: List All Configurations

Request Parameters:

{
  "PageIndex": 1,
  "PageSize": 50,
  "Name": "",
  "Order": "create_time",
  "Ascending": false
}

Response: See the success response in Section 3.1.

4.2 Advanced Example: Find a Kiosk Configuration by Name, Sorted A→Z

Request Parameters:

{
  "PageIndex": 1,
  "PageSize": 20,
  "Name": "kiosk",
  "Order": "config_name",
  "Ascending": true
}

Then filter the returned Configs[] client-side by base_setting.type == "Kiosk" (there is no server-side type filter).

4.3 Error Example: PageSize Out of Range

Request Parameters (error — PageSize is 100):

{
  "PageIndex": 1,
  "PageSize": 100,
  "Name": "",
  "Order": "create_time",
  "Ascending": false
}

Response:

{
  "Configs": [],
  "Pagination": {},
  "Hint": "Set page_size to an integer between 1 and 50, then retry.",
  "Retryable": false,
  "OriginalStatusCode": 0,
  "StatusCode": -1,
  "ErrorMessage": "Invalid page_size. Must be between 1 and 50."
}

5. Error Handling

5.1 AB Three-Layer Error Codes

This Action's StatusCode semantics:

• HTTP 429 → StatusCode = 500, Retryable = true (wait 10-30 seconds, retry once)
• Other HTTP non-200 → StatusCode = 500; Retryable = true only for HTTP 500/502/503/504
• Business errors (code != 1 in the upstream body) → StatusCode = 200, non-empty ErrorMessage, Retryable = false

5.2 Common Errors

5.3 Agent Self-Healing Decision Table

6. Best Practices

6.1 Performance Optimization

• Filter by Name before paginating: Reduces total pages and response size
• Keep PageSize modest (20-50): Config rows can carry large nested settings objects
• Sort by update_time descending when auditing recent changes, so page 1 contains what you need

6.2 Security Considerations

🟢 Read operation: No destructive side effects.

• base_setting.config_password (Kiosk exit/settings password) is returned in the list — treat it as sensitive; do not log it or expose it in user-facing summaries.

6.3 Idempotency

Idempotency: Naturally idempotent. Read-only; identical parameters return the same result unless configurations changed in between.

7. Related Tools

7.1 Follow-up Tools

7.2 Similar Tool Comparison

8. Tool Chains

8.1 Resolve Configuration Name to Full Settings

Scenario: You know a configuration by name and need its full settings.

Tool Chain:

List Policy and Kiosk Configurations → Get a Configuration

Steps:

1. Call List Policy and Kiosk Configurations with Name = "Retail Kiosk"
2. Pick the intended row from Configs[] (check base_setting.type and platform_type)
3. Call Get a Configuration with Id = base_setting.config_id

8.2 Audit Deployment of Recently Updated Configurations

Scenario: Find recently changed configurations and verify their rollout status.

Tool Chain:

List Policy and Kiosk Configurations → Get Config File Deployment Status

Steps:

1. Call List Policy and Kiosk Configurations with Order = "update_time", Ascending = false
2. For each configuration of interest, call Get Config File Deployment Status with ConfigId = base_setting.config_id
3. Check each device's progress in ApplyInfo.open_status[]

Appendix Reference:

• Field Reference: ./Field Reference.md
• Error Code Quick Reference: ./Error Codes.md