Criteria

A JSON representation of criteria for directory queries.

Criteria object

{
    "objectTypes": [
    {
        "type": "<objectTypeName>",
        "items": <CompoundCriteriaItem>
    },
        {
        "type": "<objectTypeName2>",
        "items": <CompoundCriteriaItem>
    }
    ...
    ]
}

Attributes

objectTypes array

An array of object types this criteria should match.

 Show attributes

objectTypes.type string

The name of the object type. To apply criteria to all object types, specify an empty string.


objectTypes.items CompoundCriteriaItem

A compound criteria item that contains criteria items applied to this object type.


Examples

 All users and computers
{
    "objectTypes": [
    {
        "type": "user",
        "items": {}
    },
    {
        "type": "computer",
        "items": {}
    }
    ]
}
 All groups with empty description
{
    "objectTypes": [
    {
        "type": "group",
        "items": {
            "type": "Compound",
            "items": [
            {
                "type": "Simple",
                "property": "description",
                "operator": "empty",
                "values": [{ "type": 6, "value": true }]
            }
            ]
        }
    }
    ]
}
 Objects created after May 4, 2022
{
    "objectTypes": [
    {
        "type": "",
        "items": {
            "type": "Compound",
            "items": [
            {
                "type": "Simple",
                "property": "whenCreated",
                "operator": "gt",
                "values": [{ "type": 9, "value": "2022-05-04T09:00:00Z" }]
            }
            ]
        }
    }
    ]
}

Compound criteria item

A compound criteria item acts as a container for other criteria items. It allows you to combine multiple criteria items with a logical operator, And or Or.

{
    "type": "Compound",
    "items": [
        <CriteriaItem1>,
        <CriteriaItem2>
        ...
    ],
    "logicalOperator": "<logicalOperator>"
}

Attributes

type enum

The type of this criteria item. Equals "Compound" or 1.


items CriteriaItem array, optional

An array of criteria items.


logicalOperator enum, optional

The logical operator that combines the nested criteria items. If not specified, defaults to Or.

 Show possible enum values
Or          = 0,
And         = 1

Examples

 Two simple criteria items combined with And
{
    "type": "Compound",
    "items": [
    {
        "type": "Simple",
        "property": "accountDisabled",
        "operator": "eq",
        "values": [{ "type": 6, "value": false }],
    },
    {
        "type": "Simple",
        "property": "accountExpires",
        "operator": "expired",
        "values": [{ "type": 6, "value": false }],
    }
    ],
    "logicalOperator": "And",
}

Simple criteria item

A simple criteria item is, effectively, a condition a directory object must meet to match the criteria.

{
    "type": "Simple",
    "property": "<propertyName>",
    "operator": "<comparisonOperator>",
    "values": [
        { "type": "valueType", "value": "<value>" },
        { "type": "valueType", "value": "<value>" },
        ...
    ],
    "valueLogicalOperator": "<logicalOperator>"
}

Attributes

type enum

The type of this criteria item. Equals "Simple" or 0.


property string

The directory object property to compare with the specified value(s).


operator string

The comparison operator. For a list of available comparison operators, see How to build criteria.


values value array

An array of values for the specified property to match.

 Show attributes

values.type enum

Value type. Must match the property type defined in your directory schema.

 Show possible enum values
DN                 = 1,  // DN syntax properties e.g. Manager or Assistant
String             = 2,  // Case-sensitive string
Boolean            = 6,  // Boolean
Integer            = 7,  // Integer
Binary             = 8,  // Binary properties e.g. Logon Hours property
DateTime           = 9,  // Generalized time
LargeInteger       = 10, // Large integer
Timestamp          = 14, // Timestamp

values.value value

A value for the specified property to match.


valueLogicalOperator enum

The logical operator for evaluating multiple values. Should be specified only if multiple values are included in the values attribute.

 Show possible enum values
Or          = 0,
And         = 1

Examples

 Name starts with My
{
    "type": "Simple",
    "property": "name",
    "operator": "startsWith",
    "values": [{ "type": 2, "value": "My" }]
}
 Department is Marketing or Sales
{
    "type": "Simple",
    "property": "department",
    "operator": "eq",
    "values": [
        { "type": 2, "value": "Marketing" },
        { "type": 2, "value": "Sales" }
    ],
    "valueLogicalOperator": "Or"
}
 Account will expire in 7 days
{
    "type": "Simple",
    "property": "accountExpires",
    "operator": "willOccurIn",
    "values": [{ "type": 7, "value": 7 }]
}

Advanced criteria item

An advanced criteria item lets you use an LDAP filter for search queries. Can only be used in on-premises Active Directory domains.

{
    "ldapFilter": "<ldapFilter>",
    "type": "Advanced"
}

Attributes

type enum

The type of this criteria item. Equals "Advanced" or 2.


ldapFilter string

An LDAP filter.


Examples

 Users with empty description
{
    "type": "Advanced",
    "ldapFilter": "(&(sAMAccountType=805306368)(!(description=*)))"
}

Building JSON criteria

There are two ways to quickly obtain a JSON representation of criteria.

User interface

When you copy criteria or a criteria item to the clipboard in Adaxes user interface, it is copied in the JSON format.

Programmatically

You can build criteria using the Criteria class and then convert it to JSON using the ToJson method. For example:

PowerShell
# Users from Sales department 
$criteria = New-AdmCriteria "user" {department -eq "Sales"}
$jsonCriteria = $criteria.ToJson($null)
C#
using Softerra.Adaxes.Directory.Criteria;

class Program
{
    static void Main()
    {
        // Users from Sales department
        Criteria criteria = new();
        criteria.AddType("user", 
            new SimpleCriteriaItem()
            {
                Property = "department",
                Operator = "eq",
                Values = { "Sales" }
            }
        );

        // Convert to JSON
        string jsonCriteria = criteria.ToJson(null);
    }
}

For more details about building criteria, see How to build criteria.

See also