How to build criteria

Criteria enables you to create queries for retrieving directory objects that match specific rules.

To create criteria in scripts, use the New-AdmCriteria cmdlet.

$criteria = New-AdmCriteria

By default, the criteria is empty and will match all objects. You can refine the query to return only objects of a certain type. Note that the object type name must be specified exactly as it is defined in your directory schema.

# Only user accounts
$criteria = New-AdmCriteria -Type "user"

You can also add object types to an existing criteria, using the AddType method.

# Users and computers 
$criteria = New-AdmCriteria
$criteria.AddType("user").AddType("computer")

Wildcard object type

The * object type enables you to set criteria for all objects.

# All objects with empty description
$criteria = New-AdmCriteria -Type "*" -Expression {description -empty $true}

Criteria specified for * will not be applied to an object type if it is explicitly included along with *. That object type will have its own criteria instead.

# All objects with empty description
$criteria = New-AdmCriteria "*" {description -empty $true}

# and ALL users
$criteria.AddType("user")

Criteria expressions

Expressions enable you to build queries that match only objects with specific property values. A valid expression must contain a property name, a comparison operator, and a value to compare with.

 Available comparison operators {id=comparison_operators}

  • Operator

  • Description

  • eq

  • Is equal to

  • ne

  • Is not equal to

  • empty

  • Is empty

  • startsWith

  • Starts with

  • notStartsWith

  • Doesn't start with

  • endsWith

  • Ends with

  • notEndsWith

  • Doesn't end with

  • contains

  • Contains

  • notContains

  • Doesn't contain

  • lt

  • Is less than. Works with date properties – means before the specified date.

  • le

  • Is less than or equal to. Works with date properties – means before or on the specified date.

  • gt

  • Is greater than. Works with date properties – means after the specified date.

  • ge

  • Is greater than or equal to. Works with date properties – means after or on the specified date.

  • willOccurInLessThan

  • Will occur in less than N days. Available only for date properties.

  • willOccurInMoreThan

  • Will occur in more than N days. Available only for date properties.

  • willOccurIn

  • Will occur in exactly N days. Available only for date properties.

  • occurredLessThan

  • Occurred less than N days ago. Available only for date properties.

  • occurredMoreThan

  • Occurred more than N days ago. Available only for date properties.

  • occurredAgo

  • Occurred exactly N days ago. Available only for date properties.

  • expired

  • Has expired. Available only for the Account Expires property.

For example:

# Users from the Sales department
$criteria = New-AdmCriteria -Type "user" -Expression {department -eq "sales"}

The wildcard character * can be used in expressions, but only if the comparison operator is eq or ne.

# CORRECT: Telephone numbers in the format (XXX) XXX-XXXX
{telephoneNumber -eq "(*)*-*"}

# This is INCORRECT
{telephoneNumber -startsWith "(*)"}

To evaluate more than one property, expressions can be concatenated with the AND and OR operators. Parentheses can also be used to control the evaluation order.

# User accounts from Marketing or Sales departments.
$criteria = New-AdmCriteria "user" `
    {department -eq "sales" -or department -eq "marketing"}

# Expired user accounts from Marketing or Sales departments.
$criteria = New-AdmCriteria "user" `
    {accountExpires -expired $true -and (department -eq "sales" -or department -eq "marketing")}

The entire criteria can usually be created using a single expression. In cases where it is not possible, you can use the Add method to add extra criteria to an object type.

# Users and groups whose name starts with Admin
$criteria = New-AdmCriteria "user", "group" {name -startswith "admin"}

# but only security groups
$criteria["group"].Add({groupType -eq "security"})

Virtual search properties

Adaxes offers virtual search properties that simplify creating certain criteria. Such properties are calculated on the fly, and provide convenient access to property values that are stored obscurely (e.g. userAccountControl, groupType).

For example, to create criteria that matches all disabled user accounts, use the AccountDisabled virtual property.

New-AdmCriteria -Type "user" -Expression {accountDisabled -eq $true}

For a full list of virtual search properties, see Virtual search properties.

Examples

 Users

Users who must change their password at next logon 

$criteria = New-AdmCriteria "user" {changePasswordAtLogon -eq $true}

Users who changed their password more than 10 days ago 

$criteria = New-AdmCriteria "user" {pwdLastSet -occurredMoreThan 10}

Users with passwords that never expire 

$criteria = New-AdmCriteria "user" {passwordNeverExpires -eq $true}

Users not required to have a password 

$criteria = New-AdmCriteria "user" {passwordNotRequired -eq $true}

Users whose account expires within the next 7 days 

$criteria = New-AdmCriteria "user" {accountExpires -willOccurInLessThan 7}

Users whose account is locked 

$criteria = New-AdmCriteria "user" {lockout -eq $true}

Guest user accounts 

$criteria = New-AdmCriteria "user" {guest -eq $true}

Users with Allow Access on the Dial-in tab 

$criteria = New-AdmCriteria "user" {msNPAllowDialin -eq $true}

All members of the specified group, including members of nested groups 

$criteria = New-AdmCriteria "user" {memberOf -eq "CN=My Group,OU=Groups,DC=domain,DC=com"}

Direct members of the specified group 

$criteria = New-AdmCriteria "user" {directMemberOf -eq "CN=My Group,OU=Groups,DC=domain,DC=com"}

Users with primary group other than Domain Users 

$criteria = New-AdmCriteria "user" {primaryGroupID -ne 513}

All subordinates of the specified user 

$criteria = New-AdmCriteria "user" {allManagers -eq "CN=John Smith,OU=People,DC=domain,DC=com"}

Direct reports of the specified user 

$criteria = New-AdmCriteria "user" {manager -eq "CN=John Smith,OU=People,DC=domain,DC=com"}

Manager of the specified user 

$criteria = New-AdmCriteria "user" {directReports -eq "CN=John Smith,OU=People,DC=domain,DC=com"}

All managers of the specified user, including managers of managers 

$criteria = New-AdmCriteria "user" {subordinates -eq "CN=John Smith,OU=People,DC=domain,DC=com"}

All owners of the specified group 

$criteria = New-AdmCriteria "user" {managedObjects -eq "CN=My Group,OU=Groups,DC=domain,DC=com"}

Direct owners of the specified group 

$criteria = New-AdmCriteria "user" {directManagedObjects -eq "CN=My Group,OU=Groups,DC=domain,DC=com"}

Primary owners of the specified group (via the Managed by (Primary) property) 

$criteria = New-AdmCriteria "user" {managedObjectsPrimary -eq "CN=My Group,OU=Groups,DC=domain,DC=com"}

Shared mailboxes 

$criteria = New-AdmCriteria "user" {mailboxType -eq "shared"}

Users without mailboxes 

$criteria = New-AdmCriteria "user" {mailboxType -eq "none"}

Mail enabled users 

$criteria = New-AdmCriteria "user" {mailEnabled -eq $true}
 Groups

Security groups 

$criteria = New-AdmCriteria "group" {groupType -eq "security"}

Mail-enabled security groups 

$criteria = New-AdmCriteria "group" {groupType -eq "mail-enabled security"}

Groups created after March 1, 2020 

$criteria = New-AdmCriteria "group" {whenCreated -gt "March 1, 2020"}

Rule-based groups 

$criteria = New-AdmCriteria "group" {membershipType -eq "rule-based"}

All groups the specified user is a member of, including nested groups 

$criteria = New-AdmCriteria "group" {members -eq "CN=John Smith,OU=People,DC=domain,DC=com"}

Groups the specified user is a direct member of 

$criteria = New-AdmCriteria "group" {directMembers -eq "CN=John Smith,OU=People,DC=domain,DC=com"}

Groups managed by the specified user 

$criteria = New-AdmCriteria "group" {owners -eq "CN=John Smith,OU=People,DC=domain,DC=com"}

Groups where the specified user is a direct owner 

$criteria = New-AdmCriteria "group" {directOwners -eq "CN=John Smith,OU=People,DC=domain,DC=com"}

Groups where the specified user is a primary owner (via the Managed by (Primary) property) 

$criteria = New-AdmCriteria "group" {managedByPrimary -eq "CN=John Smith,OU=People,DC=domain,DC=com"}

Groups where the specified user is the direct primary owner (via the Managed by (Primary) property) 

$criteria = New-AdmCriteria "group" `
    {directManagedByPrimary -eq "CN=John Smith,OU=People,DC=domain,DC=com"}
 Computers

Enabled computer accounts 

$criteria = New-AdmCriteria "computer" {accountDisabled -eq $false}

Read-only domain controllers 

$criteria = New-AdmCriteria "computer" {computerType -eq "rodc"}

Computers running Windows Server 2019 

$criteria = New-AdmCriteria "computer" {operatingSystem -startsWith "Windows Server 2019"}

Computers managed by the specified user 

$criteria = New-AdmCriteria "computer" {owners -eq "CN=John Smith,OU=People,DC=domain,DC=com"}

Computers where the specified user is a direct owner 

$criteria = New-AdmCriteria "computer" {directOwners -eq "CN=John Smith,OU=People,DC=domain,DC=com"}

Computers where the specified user is a primary owner (via the Managed by (Primary) property) 

$criteria = New-AdmCriteria "computer" `
    {managedByPrimary -eq "CN=John Smith,OU=People,DC=domain,DC=com"}

Computers where the specified user is the direct primary owner (via the Managed by (Primary) property 

$criteria = New-AdmCriteria "computer" `
    {directManagedByPrimary -eq "CN=John Smith,OU=People,DC=domain,DC=com"}
 Miscellaneous

Objects created yesterday 

$criteria = New-AdmCriteria "*" {whenCreated -occurredAgo 1}

Phone numbers in (xxx) xxx-xxx format 

$criteria = New-AdmCriteria "user" {telephoneNumber -eq "(*)*-*"}

Remote mailboxes 

$criteria = New-AdmCriteria "user" {mailboxType -eq "remote"}

All object types except room mailboxes 

$criteria = New-AdmCriteria "*" {objectType -ne "adm-RoomMailbox"}

Organizational units with name starting with Office or Region 

$criteria = New-AdmCriteria "OrganizationalUnit" `
    {name -startsWith "Office" -or name -startsWith "Region"}

Microsoft Entra objects synchronized from Active Directory domain acme.com 

$criteria = New-AdmCriteria "*" {onPremisesDomainName -eq "acme.com"}

Objects only from Microsoft Entra managed domains 

$criteria = New-AdmCriteria "*" {directoryType -eq "azure"}

Requirements

Minimum required version: 2023

See also

© Softerra 2022. All rights reserved.
Send feedback