What is the Custom Tools View?

The ADHQ Custom Tools View is used for creating, modifying, and testing ADHQ custom tools. Before we get into how exactly the Tool Editor works, let's start by going over some terminology:

Operation
Operations are the basic building blocks of ADHQ Tools. An operation is a small set of controls that can be used to modify a group of related Active Directory attributes.

Controls
A control is an input field that links to an AD Attribute. Controls come in several different flavours, including checkboxes, radio buttons, text fields, grids, time controls, etc.

Operation Groups
Within ADHQ Tools, operations are collected into operation groups. An operation group is primarily a way to organize operations visually.

ADHQ Tool
A tool is a collection of operation groups. Tools can be assigned to the Custom Tools menu on the Home and Collections views, scheduled to run as part of a Scheduled Task, or just created and run directly from the Custom Tools view.

Because they are used in so many different contexts, ADHQ Tools are an important part of the overall ADHQ experience. For this reason, it is important to understand how the Custom Tools View works. The following sections of this article will describe the different parts of the Tool Editor interface, with an eye toward how you can use the editor to create custom tools of your own.


Tool View Layout



General

The Custom Tools View in ADHQ is all about creating and modifying ADHQ Custom Tools. The interface is divided into five main panes, described in detail below.

The Ribbon
The ribbon is positioned across the top of the interface, and has buttons to switch tool categories, create a new tool, or modify the currently open tool.

Tool List
The Tool List is shown on the far left side of the interface. It contains the custom tools within the selected category in the ribbon bar.

Operation Tree
The Operation Tree displays a hierarchical view of the currently open tool. The tool appears at the top of the tree and below that, Operation Groups, Operations, and Controls appear.

Properties Pane
The Properties Pane shows the properties of the Tool, Group, Operation, or Control selected in the Operation Tree.

Preview Pane
The Preview Pane is shown on the far right side of the interface, and displays a preview of the selected tool. Click on a Group, Operation, or Control here to select it in the Operation Tree and load its properties into the Properties Pane.

The Ribbon



The ribbon in the report view provides three primary functions:

  1. Switching between tool categories
  2. Modifying the current category by adding, removing, or editing tools
  3. Customizing the tool menus on the Home View ribbon

You can switch between tool categories by clicking one of the buttons in the Tool Types panel. Selecting a tool category from the ribbon populates the Tool List with tools from that category. By default, the Add Tools category is selected.

The buttons in the Tool Editor panel of the ribbon are used for modifying the currently selected category. The New button will create a new tool. The Delete button will remove the selected tool from the Tool List. The Make a Copy button will make a copy of the selected tool. The Save button is used to save any modifications to the currently open tool. Finally, the Run Now button will allow you to test the currently selected tool.

Lastly, the Edit Custom Tools Menu button is used to control which tools will appear in the Custom Tools menus in the Home View and Collections View. For more information about customizing the Custom Tools menus, click here.

Tool List



The Tool List shows the tools contained within the selected category in the ribbon. Selecting a tool from this list will open the tool, loading it into the Operation Tree, Properties Pane, and Preview Pane to the right.

Sharing Levels

Custom Tools are sorted into three levels: My Custom Tools, Profile Custom Tools, and Global Custom Tools. My Custom Tools are stored locally on your machine, Profile Custom Tools are shared with all users of your profile, and Global Custom Tools are shared with all ADHQ users. Depending on your profile permissions, you may see only a subset of these levels. Custom Tools that you can use but not modify will be shown in the tree with a Locked icon. When locked custom tools are selected, the Operation Tree and Properties Panes are hidden, and you will not be able to make changes to the tool.

Operation Tree



The Operation Tree displays a hierarchical view of the currently selected tool in the Tool List. The tool appears at the top of the tree and below that, Operation Groups, Operations, and Controls appear. Selecting an item in this tree will show its properties in the Property Pane and highlight the item with a red border in the Tool Preview pane.

The Operation Tree has a toolbar in the upper right corner containing the following buttons:

Button Description
New Group Add a new Operation Group to the tool. The new group will be added at the bottom of the tool.
New Operation Click this button to launch the Add Operation Dialog for adding operations to the currently selected Operation Group. Select one or more operations from the group, then click OK to add them to your tool. The operations in the Add Operation Dialog are organized in default groups. If you'd like to insert your selected operations into these same groups in your tool, select the Group line in addition to the Operations (Ctrl + Lt Click). When you click OK, the operations you selected will be inserted into groups of the same name in your tool.
Delete Remove the selected Operation Group or Operation from the tree.
Move Up Move the selected Operation Group or Operation up toward the top of the tool. Operations cannot be moved outside of their Operation Group.
Move Down Move the selected Operation Group or Operation down toward the bottom of the tool. Operations cannot be moved outside of their Operation Group.

Properties Pane

The Properties Pane is located immediately below the Operation tree and contains all of the properties for the currently selected Tool, Operation Group, Operation, or Control. The following tables describe the properties for each type of object:

Tool Properties

Property Description
Name The name of the tool. This is the name shown in the Tool List.
Description A description of the tool.
Display Title The display title of a tool is the text that appears at the top of the tool window in large font when the tool is launched. If no display title is specified, the tool name will appear here.
Hide Tool UI Choose to hide the tool interface from the user by checking this checkbox..
Note: This box should remain cleared unless the tool has all settings filled within the Tool Editor, as you will not have an opportunity to fill out the settings at run time.
Hide Tool Output Hide the tool output from the user. This can be useful for tools that do not provide useful feedback to the user. For example, the Open Home Page tool for Users simply opens the user's website in a browser. No additional feedback is required, so this property is checked.
Output This group of options controls what happens after a tool is ran. The first option Use Global Output is selected by default and uses the output settings set in the Tool Output page of the options dialog from the file menu. If unselected, the tool will use the settings set below, including saving the tool output and automatically sending an email.

Operation Group Properties

Property Description
Name The name of the operation group, as it will appear in the tool during execution.
Description A description of the operation group.
Hide Hide the operation group in the Tool UI. The group will not be displayed during execution, but its operations will still be executed.
Expanded Show the group in its expanded state. Regardless of this setting, the user will be able to collapse/expand the group by clicking the icon on the right side of the group's title bar.
Show Subtitles Display child Operations in groupboxes with title bars. This is entirely a visual property.

Operation Properties

Property Description
Name The name of the operation, as it will appear in the tool during execution.
Description A description of the operation.
Hide Hide this operation, but use the default settings of its controls. The operation will not be displayed during execution, but its settings will be used to modify the object.

Control Properties

Property Description
Name The name of the control. This is a read-only property used to identify the control.
Description A description of the tool.
Label Change the label text for this control.
Disable Disable this control, but use its default setting. The control will be displayed in a disabled state during execution, and its settings will be used to modify the object.
Required Make this control a required field. This will force the user to supply input for the control during execution.
Auto Generate Specify a template to automatically generate the text for this control as other fields are changed in the tool interface. For example, if you set the Auto-generate template for the Display Name field to %FirstName% %LastName%, then as the user enters a First Name and Last Name into the interface, the Display Name field will be updated accordingly.
This is friendlier than simply putting %FirstName% %LastName% as a default value for the field, as it actually updates in real time showing the user exactly what text will be used for the Display Name.

The Properties Pane also has a small description field along the bottom of the pane. This is used to show a short description of the selected property. If you ever forget what a property does, select it and look in this area to get a quick reminder.


Preview Pane

The Preview Pane displays a preview of the tool as it will appear for the user during execution. Selecting a Operation Group, Operation, or Control here will select it in the Operation Tree and load its properties into the Property Pane. In the preview pane, you can interact with the tool just as you will during execution. In this way, you can set up default values for each of the Controls.

For instance, if you wanted your Add User tool to set the user's Display Name with their First Name followed by their Last Name, you could enter the template %FirstName%%LastName% into the Display Name control. Then, you could lock down the Display Name control by checking its Disable property in the Property Pane.


Edit Custom Tools Menu Dialog

The Edit Custom Tools Menu dialog is used to control which custom tools will appear in the Home View and Collection View Custom Tools menus. The Custom Tools menus are also displayed when right-clicking on an object from the Home Tab. To access the Edit Custom Tools Menu Dialog, click the Edit Custom Tools Menu button in the ribbon.



The Customize Tool Menus Dialog consists of a Menu List on the left side, and an editor for the currently selected menu on the right. The following sections will explain the different pieces of the dialog:

Menu List

The Menu List contains the Custom Tools menus and any submenus within them. Depending on the permissions of your profile, you may see the Custom Tools for your profile and the Global Custom Tools in addition to your personal list. Select a menu from this list to load its contents into the Menu Editor on the right side of the dialog.

Menu Editor

The Menu Editor is on the right side of the Customize Tool Menus dialog, and is used to modify the currently selected menu. The Menu Editor consists of two parts, a preview of the menu on top, and a property pane below that shows the properties of the selected item in the menu preview. Use the Name and Icon properties to customize how the menu item will appear in the Custom Tools menus throughout the program. In the top right corner of the menu editor is a toolbar containing the following buttons:

Button Description
Add Tool Add a tool to the selected menu.
Add Submenu Adds a submenu to the selected menu. Once a submenu is added, it will appear as a new menu in the Menu List to the left. Select the new submenu from this list to load it into the Menu Editor and add tools to it.
Add Separator Adds a separator to the menu. Separators are aesthetic menu items used to divide the menu contents visually.
Delete Removes the currently selected item from the menu.
Move Up Moves the currently selected item up.
Move Down Moves the currently selected item down.

Custom Tool Menu Contents

While all tools added to a menu will always appear in the menu, only tools applicable to the chosen object will be enabled. You can't run a "Modify Group" tool on a User object, for instance, so that tool would only be available if a group (or Group collection) was selected.