Frequently Asked Questions

General

My ribbon bar disappeared. How do I get it to come back?

The ribbon at the top of the interface can be expanded or collapsed by clicking on the collapse arrow, by using the keyboard shortcut Ctrl and F1, or by double-clicking on the currently selected tab.

When collapsed, the ribbon will only show the tab names, and will display in full temporarily after clicking on a tab name until you select a ribbon item or move the focus back to the main interface.

If your ribbon bar has disappeared completely (not even the tab names are visible), you'll need to reset your interface back to its default settings. This can be done by either reinstalling the program, or by deleting the following registry key (and subkeys):

What is a Common Property, and how is it different than an Active Directory attribute?

Common Properties are special names that map to Active Directory attributes, and are usually displayed when the corresponding attribute name is not necessarily obvious. For example, as you might expect, the Common Property First Name maps to the attribute givenName. Some other attributes, like userAccountControl, are bitfield attributes which contain multiple settings. For these attributes, we've created Common Properties that help expose these individual settings, making it easier to set them or report on them. The Disabled Common Property, which reflects one of the userAccountControl bits, is an example of this type of Common Property.

The following table contains a list of the most common Common Properties, along with the attributes they map to, if any. Common Properties that differ only in capitalization or spacing from the corresponding attribute have been excluded.

What is a Child Attribute?

Some attributes in Active Directory refer to other Active Directory objects. Attributes of these referenced objects are known as Child Attributes in ADHQ. Child attributes can be displayed on reports, or used to filter items in collections.

For example, the Member Names property of a group contains the Distinguished Name of all of the group's members. If we wanted to report on the members' email addresses, we can do that by first selecting the Member Names property to retrieve the group's members, then selecting the "Child attribute" Email Address as shown in the image below from the built-in group report "Member Information":

You'll notice a field called Object Type in the screenshot above. This field allows us to choose which set of attributes we want to see in the lists below. For instance, say we want to create a report showing the direct members of all of the groups in the directory, and in the case where the group member is another group, show that group's member count. Like in the screenshot above, we'd select Member Names as the base attribute, but when we try to select the "Member Count" child attribute, it isn't in the list because "Member Count" is not a valid attribute for User objects. Change the Object Type to "Group", and ADHQ will now give the option to show the member's "Member Count" property. This "Member Count" child attribute will simply return nothing when run against one of the group members that isn't also a group.

Templates & Parameters

What are templates and how do I make one?

Many fields within ADHQ can take values which reference other fields. These special fields are called Template fields, and you'll be able to recognize them by the stylized 'T' icon to the right of the field.

Clicking on the Template icon will display a list of suggested templates for this field. Select one of these if they meet your needs, or select "Custom Template" to launch the Template Editor, which can help you design your own template.

The Template Editor contains a template field like the one in the tool, as well as a row of buttons above that are used to modify parameters within the template. Use the Add button to insert a new parameter into the template at the cursor position with the Add a Parameter dialog, and the Edit and Delete buttons to modify or remove the selected parameter.

When adding or editing a parameter, use the grid at the top of the Add/Edit Parameter dialog to select a Common Property or Active Directory attribute to include within the template. The bottom half of the dialog contains display options for the parameter. These depend on the specific attribute selected, but typically include length and formatting options.

As you grow more comfortable with templates, you can bypass using the Template Editor and instead enter your template directly into the field. When manually entering a template, type a percent sign % to begin inserting a parameter and you'll be prompted with a list to choose from. After typing the parameter name and before the closing percent sign, you can type a colon : to show a list of formatting options available for the parameter, as shown below.

What are backup templates?

Some template fields can contain multiple templates, in the event that the first template resolves to a value that already exists in your domain. We call this feature "Backup Templates", and it is accessed by clicking on the field's Template icon and choosing Modify Backup Templates.

Selecting this option will launch a special version of the Template Editor dialog that allows you to enter multiple templates. Use the Add button to insert a new template by either selecting a suggested template or creating a custom one. The Copy button will create a duplicate of the selected template and add it to the end of the list. And, as you might expect, the Modify and Delete buttons can be used to edit or remove the selected template. Templates can be reordered with the Move Up and Move Down buttons.

The templates listed here will be resolved in order to find a possible value for the field. If the primary template is already in use in your domain, the tool will try to use the first backup. If that is also in use, the second backup will be used, etc. If none of the templates provided here resolve to a unique value, the value will not be set. If you were attempting to create a new user account with a unique Netbios Name, for example, this failure would result in an error, allowing you to address the issue by manually picking a name for the user.

What's the %FormatText% parameter? It always shows up blank for me.

Most template parameters are simply reflections of AD Attributes or Common Properties. But %FormatText% works slightly differently in that it has no resolved value. Instead, when added to a template, this parameter affects how the entire template is displayed.

The following table contains a list of the %FormatText% parameter options, along with a description of what they do and an example of how their use would affect the template text, assuming the initial value was TeMpLåTe TeXt.

Office 365

Does ADHQ support Office 365 environments?

ADHQ provides the ability to create Office 365 accounts for accounts on your local network. It can also add or remove licenses, or modify the existing licenses assigned to a user. With respect to information gathering, ADHQ can report on several Office 365 attributes for your users including Last Sync Time, Office 365 Logon Name, Sign-In Blocked, Licenses, and Usage Locations. See the complete list of Office 365 attributes that can be reported on by adding a new column to a report. The Office 365 Common Properties have names starting with "Office 365".

How do I create an Office 365 mailbox with ADHQ?

Simply assign a license for the Exchange Online service plan when creating a user, as shown in the screenshot below.

In hybrid environments, if you want to manage the user's mailbox from your local Exchange Admin Center, you'll need to check the option to create an Exchange Remote Mailbox in the Mail operation group. Without this option selected, the user's Office 365 mailbox will not be displayed in the Exchange Admin Center and will have to be managed exclusively through the Office 365 web interface.

Can I block users from signing in to Office 365 with ADHQ?

In its default configuration, Azure AD Connect will synchronize the Disabled state of local accounts with the Block Sign-In flag for Office 365 accounts. To disable a user, check the "Account is disabled" checkbox in the Security operation group. This setting will be reflected in your Office 365 environment after the next automatic sync (by default, every 30 minutes).

When I right-click on a user, I don't see the option to modify the user's Office 365 licenses. Why not?

The ability to modify the Office 365 licenses is controlled by whether we can locate a corresponding user in the Office 365 environment. ADHQ attempts to find the user with the following techniques:

• get the user's ID from the msDS-ExternalDirectoryObjectId attribute
• use the user's userPrincipalName (e.g. [email protected])
• use the user's sAMAccountName with the UPN suffix(e.g. [email protected])

If we can't retrieve these attributes, or if we can't find a user with a corresponding userID or userPrincipalName, you will not have the ability to modify Office 365 settings for the selected user. If your local domain name is not a valid domain in your Office 365 environment, or if you use a different format for your Office 365 Logon Names, you can specify a custom template on the Office 365 page of the Options dialog.

Importing

What types of files can I import with ADHQ?

ADHQ accepts CSV (comma separated value) files and TXT files as input into any of the Import tools. In the Import Wizard, ADHQ allows you to specify whether the file uses commas, asterisks, colons, semicolons, or a custom character string as the delimiter between fields. The image below shows a standard CSV file, which could be used to create new user accounts with the Import New Users tool. Click this link to download the sample file.

How do I modify values of existing attributes?

ADHQ will normally overwrite the existing value(s) of any attribute in your import files while setting the new value. If you want to retain part of the existing value, ADHQ provides several special character sequences that you can use within import files to instruct the program to modify the fields in specific ways. The following table contains a list of these special prefixes, and contains links to example files where you can see them in use.

If you want to do something more complicated with the old value of an attribute, ADHQ also supports using templates within imported values. The following link leads to an example import file, which will change a user's description from olddescription to prefix-olddescription-suffix.
Sample Import File

What's the difference between "Street", "street", and "streetAddress" on the Column Mapping page of the Import Wizard?

In addition to Active Directory attributes, the Import Wizard allows you to map columns to Common Properties. Common Properties are aliases we've created that map to Active Directory attributes, and are usually displayed when the corresponding attribute name is not necessarily obvious. See What is a Common Property? for more information.

Although we've made an effort to ensure that most Common Property names are straightforward, the "Street" Common Property is a little unusual. It does not map to the street Active Directory attribute as you might expect it to, but rather to the streetAddress attribute. This was done to better mimic Microsoft's user interfaces, which often refer to the field as "Street", even though they are setting the "streetAddress" attribute behind the scenes. This decision had the unfortunate side effect of creating confusion with the Active Directory attribute "street", which is also a valid attribute for User objects, though it is not regularly used.

To make a long description short, if you want to set the "Street" field as it appears in property sheets in Active Directory Users and Computers, use "Street" (uppercase) or "streetAddress". If you want to set the rarely-used attribute "street", map your column to "street" (lowercase).

Using Filters

How do I create a filter?

ADHQ filters are used throughout the program to limit the objects within a particular scope. You'll see them as part of collections and reports, as well as when setting up Search & Replace operations and Security Tools.

Filters consist of a set of conditions, which are grouped into Match All or Match Any groups to provide support for complex queries.

Above the filter field, there is a row of buttons. These buttons are used to modify the filter by adding conditions or groups, modifying filter items, deleting items, or shifting them around. Below is a description of each of the buttons and their purpose:

Filters are confusing. Can I see some examples?

Sure. ADHQ filters are very powerful, but unfortunately there's always a trade-off between power and complexity. It can be helpful to sit down ahead of time and figure out the exact conditions you're trying to match, and how those conditions are linked together.

Match Any groups are used when an object only has to match one condition from a group in order to pass the test. The default Inactive Users filter is a good example of a Match Any group. When trying to match a user against this filter, the first thing we do is look at the Disabled state of the user. If the user is Disabled, the Match Any group is immediately satisfied, and we don't need to look at any of the other conditions.

Match All groups are used when an object has to match all of the conditions from a group in order to pass the test. In the filter above, we are matching on Users named Joe in the state of California. If we had used a Match Any group here instead, the filter would have picked up everyone in California, as well as all the Joes from other states. But that's not what we want; we want only the Joes in California. Therefore, we use Match All.

If you were paying attention to the last 2 examples, this one should be pretty straightforward. Like Example 2, it will show all of the Joes in California. But there's a new item at the bottom of the Match All group, a Match Any group. This Match Any group is the same as the group in Example 1, which shows Inactive Users. So, this filter shows the inactive users named Joe in California.

If a user fails to meet any of the 3 items under the Match All group, he will not match. That is, if the user is not named Joe, or if the user is not in California, or if the User is not Inactive (aka "if the User is Active").

What if I switch the groups around?

Interesting question. This new filter will match users named Joe, and users in California, and users that meet all 5 conditions in the Match All group. If you look closely however, you'll see that it's not possible to meet all 5 conditions in the Match All group, because that would require the user's Last Logon attribute to be empty and equal to 0 at the same time. So, we can ignore the entire Match All group. That means the filter will simply match all users named Joe, and all users in California.

Browsing Active Directory

How can I modify the Custom Tools menu in the ribbon?

This is accomplished from the Edit Custom Tools Menu button on the Custom Tools ribbon.

Clicking this button will launch the Customize Tool Menus Dialog, from which you can modify which tools show up in this menu. The Edit Custom Tools Menu Dialog is discussed in detail here.

Is there an easy way to see the attributes of a selected object?

Yes, absolutely. This is the intended purpose of the Attributes tab of the Tab View. For instance, if you wanted to see the attributes of the user Joe Manager in your domain.net\Test Users OU, you would perform the following steps:

1. Clear the box in the ribbon labeled Show only containers in tree to make sure Joe will be visible in the tree.




2. Navigate the Active Directory Tree to the domain.net\Test Users and select Joe Manager.




3. At the bottom of the Tab View, select the Attributes tab to switch from seeing the Child Objects to seeing the AD Attributes of your selection.

Once you've performed those steps, you should see in the Attributes List, a list of Joe Manager's attributes.

What are the Configuration and Schema folders in the tree? Can I get rid of them?

The Configuration and Schema containers are top-level sub-trees shown in the Active Directory Tree pane on the left side of the ADHQ Home View.

The Configuration sub-tree stores configuration objects for the entire forest in cn=configuration,dc=forestRootDomain. Configuration objects store information about sites, services, and directory partitions. Likewise, the Schema sub-tree stores class and attribute definitions for all existing and possible Active Directory objects in cn=configuration,dc=forestRootDomain.

You can remove these folders from the tree in the Options dialog. To do so, select Options from the file menu, and navigate to the Directory page. From there, you can show or hide these folders as well as the deleted objects folder.

Can I save the list of child objects to a file?

Yep! This is accomplished on the Home Tab by clicking within the Child Objects pane and then using the Export to File button in the View panel of the ribbon.

You can also use this button to export the attributes of the currently selected object by first switching to the Attributes tab at the bottom of the Tab View.

Collections

Why should I create collections?

Using collections to modify multiple AD objects at once has a couple of benefits over selecting the objects in the Home tab:

1. Collections are useful for managing sets of objects that do not all appear in the same OU.
   The Home tab allows you to modify multiple objects at once by selecting them with the Shift or Ctrl keys. However, it is not possible to select objects in different OUs at the same time. Objects from anywhere in your domain can be added to a single collection.


2. Collections are evaluated at the time the tool is run.
   Collections can be defined by a filter. This allows collections to stay up-to-date, all the time. For example, the builtin collection Inactive Users will always contain every inactive user in the whole domain, even if new objects have been added to the domain recently, or existing objects have become inactive.

How can I add items to a collection?

The upper part of the Collection Pane shows the locations or items that make up the collection.

Use the Select button to add a location to the grid. You can add individual objects, or add every object in a container by adding the container to the scope. To add individual objects defined in a file, click the down arrow on the Select button and choose Import From File. The Set a Import File option will not automatically import objects into the grid, but rather the file will be read at the time the collection is used. You can adjust the level of each container you add to the collection by selecting the item and using the Level button to switch between Entire Subtree, This Object and Its Children, or This Object Only.

In the example image above, we are setting up the a collection to show Inactive Users. For this collection, we care about the objects in 2 containers: Javelina Software\Engineering and Javelina Software\Sales. Any users found within the Javelina Software\Engineering\Maryland container will appear in the collection, because the scope level for the Engineering container is set to Entire Subtree. On the other hand, users found within the Javelina Software\Sales\Maryland container will not appear in the collection because the Sales container is only set to a scope level of This Object and Its Children.

Is it possible to add only items that meet certain criteria?

Yep! This is the purpose of the Collection Filter, found below the location list in the Collection Pane.

The Filter pane is used to specify a series of conditions that must be met in order for the object to match. These conditions are grouped into Match All or Match Any groups to provide support for complex queries. For more information about creating filters, see How do I create a filter?

Can I rename a collection?

Of course, you can rename a collection by right-clicking on the collection in the collection tree and selecting rename. Alternatively, clicking on a previously selected collection will launch an in-place editor that you can use to change the collection's name. Locked collections (those that have a icon next to their name) cannot be renamed.

How can I view which objects match my collection?

You can view the objects within your collection with the Collection Preview button, located in the ribbon.

Previewing a collection will launch a report showing all the objects located in the location list and that match the collection filter. Use the report output to verify the collection matches the objects you need. You may also save or email the list directly from the output screen.

Ok, I've created a collection. Now what?

Now you can run ADHQ tools on your collection of objects using the tool menus in the ribbon.

The tool menus in the Collections tab are the same as the corresponding menus from the Home tab, with the Add, Properties, and Import menus missing, since these tools cannot be run on a collection of objects. To modify the Custom Tools menu, use the Edit Custom Tools Menu dialog on the Custom Tools view ribbon.

ADHQ Reports

How do I run a built-in report?

Simply select the report from the Report Tree, then click the Run button in the ribbon. A screen will appear asking you to verify the scope and output settings for the report. Click the Run Now button at the bottom of this screen and the report will run.

For example, if you'd like to run a report to find out email address information for your users, you'll want to make sure the Users category is selected in the ribbon, then choose the Email Address Information report from the list. Verify that the report shows the information you need in the Preview pane, then click the Run button in the ribbon to launch the report.

Can I create a custom report from scratch?

Yes, absolutely. Reports in ADHQ are categorized by object type. In order to create a new report, you first must choose the type of object you want to appear on the report and select the corresponding category in the ribbon.

Once you've done that, simply click on the New Report button in the ribbon, and follow the instructions in the New Report Wizard to create the report. When you've completed the wizard, your new report will appear in the Report Tree.

For more information about the New Report Wizard, click here.

How do I make my report only run on certain containers?

The Report Scope property in the Scope group of the Report Properties pane controls the containers on which the report runs. Simply click the the button to launch the Report Scope dialog.

The top of this dialog allows you to specify the objects on which the report will run. Use the Select button to add a container to the grid. If you are running an AD Object Report or a File Report, you can also select individual objects to add to the scope by clicking on the down arrow on the Select button and choosing the second option instead. To import objects from a file into the grid, select Import From File, however, if you need the report to use the objects written in the file at runtime, you may set an import file. This can be useful to run a report on the output of another report. You can adjust the scope level of each container you add to the report by selecting the item and using the Scope Level button to switch between Entire Subtree, This Object and Its Children, or This Object Only.

In the example below, we are setting the report scope for our Inactive Users report. The report is set to be run on two containers, Javelina Software\Engineering and Javelina Software\Sales. Any users found within the Javelina Software\Engineering\Maryland container will be added to the report, because the scope level for the Engineering container is set to Entire Subtree. On the other hand, users found within the Javelina Software\Sales\Maryland container will not be added to the report because the Sales container is only set to a scope level of This Object and Its Children.

Is it possible to limit which objects appear on my report?

Sure is! The Report Scope property in the Scope group of the Report Properties pane is used to limit the objects that appear on the report. Click the the button on the Report Scope property to launch the Report Scope dialog.

The bottom grid of this dialog controls the report filter. Filters are used to specify a series of conditions that must be met in order for the object to be included on the report. For more information about how to create filters, see How do I create a filter?

Instead of creating a custom filter for your report, you may load the filter and scope from a collection. This is done by clicking the load a collection dropdown on the top right of the dialog, and selecting the collection to copy the settings from. Builtin and custom collections that match the current report type will be shown.

When you're finished creating your report filter, click the Ok button to save the filter to the Report Properties.

Can I automatically email my report to my boss?

Yes. The Output group of the Report Properties pane gives you options for saving the report output to a file, or sending an email when the report is complete. Use the Use Global Output setting if you have report output settings specified in the Options dialog (available via the Options from the file menu). If you do not have global report output settings, or do not want to use the global output for this report, clear the Use Global Output checkbox and follow the instructions below to set up the Output properties: To have the report save itself to a file each time it runs, enable the Save Report property by checking the checkbox as shown in the image to the left. The type of file must also be specified by clicking the button on the File Type property and selecting the file type. Next, select a name and location for the file by clicking the buttons on the Filename and Folder properties. If you'd like to save to save the Output in addition to the report, use the corresponding settings in the Output File group. If you want to have ADHQ automatically send an email when the report is complete, you'll need to check the Send Email checkbox and set up the email properties. If you are saving the Report File or Output File, you can choose to attach these files to the email with the corresponding checkboxes. Fill in the recipient fields as you would in any other email. You can enter multiple email addresses by separating them with a semicolon. The Comments: field can be used to set the body of the email. Once that information is entered and the report is saved, an email will be sent to the recipients each time the report is run.

Scheduled Tasks

What kinds of things can I do during a Scheduled Task?

Scheduled Tasks in ADHQ are more robust compared to their equivalent in previous versions of our software. Whereas in prior versions, a scheduled task could be linked to only one tool, tasks in ADHQ can run multiple tools or reports.

Furthermore, you can add actions to a task outside of running an ADHQ tool or report. These actions, available from the button, include things like running an external program or sending an email. For more information about these kinds of actions, see Task Action Dialog.

How can I save output from my task?

Click the button to the right of the Output field in the Task Settings to modify the output settings for the task. This dialog will provide settings for saving the task output to a file or sending an email once the task is complete.

Can I run a task more than once per day with ADHQ?

Unfortunately, due to compatibility concerns with previous versions of Microsoft's Task Scheduler, ADHQ does not yet support the kind of advanced scheduling you'll find in more recent versions of Task Scheduler. There are however, a couple of workarounds if you require your task to run more than once a day:

Option 1: Use Microsoft's Task Scheduler to handle the schedule

The easiest workaround to this problem is to modify the task's schedule from within Task Scheduler. ADHQ's Scheduled Tasks are run by creating a Microsoft task of the same name. Simply open the task in Task Scheduler and modify the schedule (called Triggers in recent versions). The downside to this workaround is that ADHQ will not display your task's schedule correctly and it is easy to accidentally change the schedule back to once a day if you modify the task in ADHQ.

Option 2: Create multiple copies of your ADHQ task

Set up your task to run once a day. Then, once it is set up, create one or more copies of the task and change the schedule on the copies to handle the other times of the day. For example, if you want to run your task every 6 hours, you could set up the following tasks:

My task isn't running. What's wrong?

Newly created tasks (or copied tasks) in ADHQ default to running under the local System account. This account should be sufficient for actions like sending an email, or executing an external program. However, if you are trying to run an ADHQ tool or report from your task, you will likely need to set the task to run as a user with more permission.

Also, it's possible that the task is running, but that an error occurred while running a tool or report task action. Verify that the task output is not reporting any errors, and if you are running a tool or report, check to see if the action-specific output files are created. These output files, if they exist, should help guide you to the problem. For more information about task output files, see How can I save output from my task?

Finally, you can try running the task directly from the Run Now button on the ribbon to verify that there are no issues with your task configuration.

Custom Tools

How do I create a new ADHQ custom tool?

One feature that sets ADHQ apart from its predecessor is the ability to create completely customized tools using our Operation building blocks. In order to get started building a custom tool from scratch, use the New button in the ribbon. The Create a new tool dialog will prompt you for an Object Type, Tool Type, and a name for your new tool.

The Object type is the type of AD object your new tool will be modifying. The Tool Type is the action that will be performed on your objects. There are several tool types, as described below.

After creating a new tool, you can add operations to it by clicking the Add Operation button in the Operation List. Use the Preview Pane to specify any default values you want in the operation's control. Select an operation, operation group, or control to modify its properties. Save your new tool by clicking the Save button in the ribbon, and you're just about finished.

The last step to creating a new ADHQ tool is adding your tool to the Custom Tools menu in the Home View. This is done with the Edit Custom Tools Menus dialog. For more information about customizing the tool menus, click here.

Is it possible to model a new tool off of an existing one?

Sure, you can easily make a copy of a built-in ADHQ tool or a previously created custom tool. To base a new tool off another custom tool, select the tool in the Tool List and click the Make a Copy button in the ribbon. This will make a copy of the selected tool for you to work with.

If you'd like to make a copy of a builtin ADHQ tool, click the New Tool ribbon button and select the Copy an Existing Tool radio button. From the button you can select a builtin tool. Then, just make changes to the tool like you ordinarily would. Add or remove operations, hide operation groups, make controls read-only. When you're done fixing up your new tool with only the operations you want and all its default values set, Save the tool and add it to the Custom Tools menu with the Customize Tool Menus dialog.

Can I make an ADHQ tool, or a section of a tool, read-only?

You can make individual controls read-only by modifying the Disable property of the control. Select the control in the Operation Tree or Preview Pane, then check the Disable property in the Property Pane to disable it. Disabled controls will still appear to the user during tool execution, but their values cannot be changed.

It is not possible to make an entire Operation or Operation Group read-only, but you can hide Operations from the user during execution by adding them to their own Operation Group and checking the Hide property for the Operation Group.

How can I test a tool without messing up my Active Directory?

Any ADHQ tool can be tested by clicking the Run Now button in the ribbon. This will prompt you for an object on which to run the tool. You can either select an existing object, or have ADHQ create one for you in whichever container you'd like.

Once you select an object for testing, the tool will run as it would if selected from a tool menu on the Home View. Testing a tool in this way can help to verify that it works as intended before you add the tool to the Home View tool menus, or attempt to run the tool on multiple objects in your domain.

I can't see my tool in the Tool List. Where did it go?

First, check to make sure the tool is actually gone. ADHQ tools are sorted into categories, accessible through buttons in the ribbon.

If no tools are appearing in the Tool List for any the categories, it is possible that ADHQ has lost its connection to the tool cache. In this case, a simple restart of ADHQ should fix the problem. Close ADHQ, wait a couple minutes, relaunch it, and see if your tools reappear.