How to Customize a Directory Query
The most common question we get concerning AD queries is how to add one or more fields, called 'attributes', to Hyena's right window output. Here are the steps:
1. First, determine what level in Hyena you are going to use the query in. Hyena categorizes its AD queries based on which left-window object type is being queried, for example, All Users, All Groups, or the contents of an OU.
For this example, we will modify a query for All Users.
2. Select File > Manage Object View, then click the AD Queries tab. Select the Query Type that you determined in Step 1 to display the existing queries for that object type.
For this example, select the 'All Users' query type, then select the existing query named "Users (Detailed - General)"
3. When an existing query is selected, Hyena will display the current attributes displayed in the query in the lower left window. Individual fields can be removed or reordered as desired. To add an additional field, select it from the lower right window. If you don't see the attribute you are looking for, either change the Attribute Category, or select "Other - Specify Attribute" from the category list, and enter the directory name(s) of the attributes to add.
For this example, we will be adding the email address(es) of the user and the employee ID:
- Change the Attribute Category to 'User Attributes', find the E-Mail (mail) attribute, and click the 'Add' button.
- Change the Attribute Category to 'Microsoft Exchange Attributes', find the Email Addresses (proxyaddresses) attribute, and click the 'Add' button.
- Change the Attribute Category to 'User Attributes', find the employeeid attribute, and click the 'Add' button.
4. To change the order of newly added attributes, find and select them in the lower left window, and use the Up/Down buttons to change the display sequence.
5. Click OK to save the query.
6. To execute a query, right click on the applicable directory level whose queries were modified, select Query Active Directory, then select the name of the query that was created or modified.
For this example, right click on the All Users object in Hyena's left window, select Query Active Directory > Users (Detailed - General).
If the query modified was in the Container/OU Contents category, it can be executed by right clicking on the main Containers/OUs object, or any sub-container or OU displayed anywhere in Hyena.
How to Create a 'Ranged' Directory Query
The above example illustrated how to add one or more attributes to a directory query. Hyena can be used to issue any LDAP query against Active Directory. One of the drawbacks to the LDAP syntax is that its difficult to construct complex queries, which is why Hyena handles the complicated back end work of creating the query. For more complex tasks, Hyena permits directly specifying the LDAP command used for directory object retrieval.
In this example, a simple 'ranged' directory query will be created, which allows retrieving only a small subset of records from the directory. For large directories, this can save a great deal of time both for the server and the end-user. Often, when a user account needs to be modified, the entire user list, or the entire contents of an OU, needs to be retrieved. But if the first few letters of the directory name are known, this example will very quickly retrieve a matching subset of users:
1. First, select File > Manage Object View, select the 'AD Queries' tab, then change the Query Type to "Container/OU Contents".
2. Next, click the "New Query" button located to the right of the Existing Queries list. Enter a name such as "Ranged User Query".
3. Set the 'Default Window Assignment' to 'None'.
4. For the 'LDAP Search Filter', enter:
(&(objectCategory=person)(objectClass=user)(&(name>=%Starting Letter%*)(name<=%Ending Letter%Z*)))
Note: Cut-and-paste this command to prevent typographical errors.
5. Click the box titled "Include subcontainers and sub-OUs in search" to force the directory to retrieve anything in the selected container or sub-containers beneath it, then click OK twice.
To execute this query, select the directory level to query in Hyena's left window. To query the entire directory, select the main Containers/OUs object under the domain. To query just a single OU and any sub-OUs beneath it, select the top-level OU or container name in the left tree window. To query multiple OUs, display the OUs in Hyena's right window, then multi-select the OUs to query.
Once selected, right click, select Query Active Directory > Ranged User Query (use the name created for the query above). Hyena will prompt for the starting and ending letter range. For example, to retrieve all users with a directory name starting with either an 'A', 'B', or 'C', enter in 'a' for the starting and 'c' for the ending range. To just retrieve users with a directory name starting with 'R', enter an 'r' for both starting and ending ranges.