Search Folder

title: “Search Folder Methods”

Two methods for searching within folders: SearchAsync returns all matches, while SearchOneAsync returns exactly one result or throws an error if multiple matches are found.

SearchAsync vs SearchOneAsync

Method Returns Use Case
SearchAsync All matching objects When expecting multiple results
SearchOneAsync Single object or error When exactly one result is expected

SearchAsync

Returns all objects matching the query in the specified folder.

// Search for all people in a department
var query = "{ '_t': 'Person', 'Department': 'Engineering' }";
var results = await client.SearchAsync(folder, query, includeChildFolders: true);
var engineers = results.OfType<PersonInfo>().ToList();

SearchOneAsync

Returns exactly one matching object. Throws an exception if zero or multiple results are found.

// Get a specific person by unique identifier
try
{
    var person = await client.SearchOneAsync<PersonInfo>(
        folder,
        "{ 'EmployeeId': 'EMP-12345' }"
    );
    Console.WriteLine($"Found: {person.CommonName}");
}
catch (Exception ex)
{
    // Either no results or multiple results found
    Console.WriteLine($"Error: {ex.Message}");
}

Parameters

Parameter Type Description
folder FolderInfo The folder to search in
query string MongoDB-style JSON query
includeChildFolders bool Search child folders (default: false)
spanScope bool Search across instance scope

Best Practices

Scenario Recommended Method
List all cardholders SearchAsync
Find person by employee ID SearchOneAsync
Get all online controllers SearchAsync
Find controller by MAC address SearchOneAsync

Search Async

Example in C#

// Returns: IEnumerable<BaseInfo>
var baseInfo = await client.SearchAsync(FolderInfo folder, String query, Int32 page, Int32 pageSize, Boolean includeChildFolders, Boolean spanScope, String forTags, Int32 limit, Boolean includeParents);

title: “SearchAsync”

Search for objects in a folder using MongoDB-style query syntax. Returns all matching objects with optional pagination and child folder inclusion.

Method Signature

Task<IEnumerable<BaseInfo>> SearchAsync(
    FolderInfo folder,
    string query,
    int page = 0,
    int pageSize = 1000,
    bool includeChildFolders = false,
    bool spanScope = false
)

Parameters

Parameter Type Description
folder FolderInfo The folder to search in
query string MongoDB-style JSON query
page int Page number (0-based)
pageSize int Results per page (max 1000)
includeChildFolders bool Include child folder objects
spanScope bool Search across instance scope

Examples

C# Wrapper

// Search for all people with surname "Smith"
var query = "{ '_t': 'Person', 'Surname': 'Smith' }";
var results = await client.SearchAsync(instance, query);
var people = results.OfType<PersonInfo>().ToList();

// Search with pagination
var page1 = await client.SearchAsync(instance, query, page: 0, pageSize: 100);
var page2 = await client.SearchAsync(instance, query, page: 1, pageSize: 100);

// Search including child folders
var allPeople = await client.SearchAsync(
    rootInstance, 
    "{ '_t': 'Person' }", 
    includeChildFolders: true
);

cURL

# General search
curl -X GET \
  "https://api.acresecurity.cloud/api/f/{instance-key}?q={\"_t\":\"Person\"}&page=0&pageSize=1000&includeChildFolders=false&spanScope=false" \
  -H "Authorization: Bearer TOKEN_GOES_HERE"

# Search for controllers
curl -X GET \
  "https://api.acresecurity.cloud/api/f/{instance-key}?q={\"_t\":\"Controller\"}&includeChildFolders=true" \
  -H "Authorization: Bearer TOKEN_GOES_HERE"

Query Examples

Use Case Query
All people { "_t": "Person" }
By surname { "_t": "Person", "Surname": "Smith" }
Active cards { "_t": "Person", "CardAssignments.0": { "$exists": true } }
Online controllers { "_t": "Controller", "Status.IsOnline": true }
By department { "_t": "Person", "Department": "Engineering" }

Search One Async

Example in C#

// Returns: T
var item = await client.SearchOneAsync<T>(FolderInfo folder, String query, Boolean includeChildFolders, Boolean spanScope, Boolean includeParents);

title: “SearchOneAsync”

Search for exactly one object matching a query. Throws an exception if zero or multiple results are found. Use when you expect a unique match.

Method Signature

Task<T> SearchOneAsync<T>(
    FolderInfo folder,
    string query,
    bool includeChildFolders = false,
    bool spanScope = false
) where T : BaseInfo

Parameters

Parameter Type Description
folder FolderInfo The folder to search in
query string MongoDB-style JSON query
includeChildFolders bool Include child folder objects
spanScope bool Search across instance scope

Returns

A single object matching the query, cast to type T.

Exceptions

Exception Cause
NotFoundException No matching object found
MultipleResultsException Query matched more than one object

Examples

C# Wrapper

// Find person by unique employee ID
try
{
    var person = await client.SearchOneAsync<PersonInfo>(
        instance,
        "{ 'EmployeeId': 'EMP-12345' }"
    );
    Console.WriteLine($"Found: {person.CommonName}");
}
catch (NotFoundException)
{
    Console.WriteLine("Person not found");
}
catch (MultipleResultsException)
{
    Console.WriteLine("Query not specific enough - multiple results");
}

// Find controller by MAC address
var controller = await client.SearchOneAsync<ControllerInfo>(
    instance,
    "{ 'MacAddress': '0000-0101-0133-0566-9001' }"
);

cURL

curl -X GET \
  "https://api.acresecurity.cloud/api/f/{instance-key}?q={\"EmployeeId\":\"EMP-12345\"}&includeChildFolders=true&spanScope=false" \
  -H "Authorization: Bearer TOKEN_GOES_HERE"

When to Use

Use Case Method
Unique identifier lookup SearchOneAsync
List of results expected SearchAsync
May or may not exist SearchAsync with .FirstOrDefault()

Best Practices

Use specific queries: Ensure your query will match exactly one object. Include unique identifiers like EmployeeId, MacAddress, or Email.

Handle exceptions: Always wrap in try-catch to handle not found and multiple results scenarios.