Attribute Scope Query

The Attribute Scope Query (ASQ) provides a specific query function, with the scope of the query is based on the list of values stored in an attribute with an Object(DS-DN) format. For ease of reference within these instructions we will reference this attribute as the Search Attribute.

The query input fields have specific roles for ASQ based queries, The BaseDN must be the DN of the object containing the Search Attribute for the basis of searched, the Search Scope must be Base Level, the Filter is applied to the objects in the Search Attribute, with the Attributes field, the first attribute named must be the name of the Search Attributes, followed by the list of attributes that are required.

In the above example, we are using the member attribute as the Search Attribute of the group object and its returns the last time the user logged on and when they last changed their password.

The filter field can be used to limit\filter the records that are returned, the filter is applied to the objects in the Search Attribute and will only return the objects that match the filter, i.e. setting the filter to (&(objectclass=*)(!userAccountControl|=2)) only accounts that are enabled will be returned.  This filter is using the subst feature in the filter to simplify the entry of complicated filters, see Substitutions

Advanced operations -  it’s possible to combine the Input Mode and ASQ options to query the Search Attribute of multiple objects in a single operation.

To do this first enable the Input Mode, by selecting the Table Input option, and select the Create Multiples option, and then paste a list of object DNs to be queried into the table view.  Update the BasedDN to be ##input and click go.  The results for DN in the Search Attribute will be displayed on an individual line.

LDAP Search Input Mode

LDAP Search supports an option called Input Mode, Input Mode allow you to run a query against a list of user inputs and the results are displayed against the input item.  To enable Input Mode, the Table View and Table Input must be selected, this will enable a few extra options and items on the Table View context menu.  

When the Input mode is selected the other options in the Table View options will be enabled. Also the column names in the table view will also change to ##Input<..>, if there is already data in the table and the table contents are preserved, or when the input lists are added.  Input Mode supports up to 9 input lists.

The input lists are added to the table view by using the additional items in the context menu. These are Load Input, Paste Replace or Insert.

Load Input - will load the list from a file, the file must be tab separated
Paste Replace - this will paste the contents of the clipboard into the table view, clearing the contents of the table, copying the contents from a multiple column spreadsheet
Paste Insert - this will paste the contents of the clipboard into the table view, the existing contents of the table are preserved. 

Above shows the table view after the input lists have been added.  The column headings are updated to show the variable name for the list, these variable names can then be added to the query input fields.

In the example above only the first input variable is used in the filter, the second input is ignored.  When the query is run, the query will be run for each of the items in the list with the ##input being substituted with the value in the list.  If the query does return results the attributes are displayed on the same line as the entry.

In the example above, both variables are used in an Update Query, the ##input2 variable is used to update the department name of the user.

LDAP Search Update Queries

NetTools supports the ability to not just query the directory, but also perform update as well. Because writing to a directory comes with some risks, there are number of safe guards to make sure that you update the directory by intent and not by mistake.

To use the Update option you have to input the required details in the Attributes field, see the syntax below, you then need to select the Enable Updates option. This will enable the preview mode by default as an extra safety net.  Preview mode allow you to run the query and show the values that would be written to the attributes when the preview mode is turned off.  When Preview mode is deselected the Go button turns red to show that the update mode is enabled and attributes could be changed when the query is run.  Please note, there is no undo option for updates.  When you run an update query the values returned against each of the attributes are the new value for the attributes after the update has been completed.  If an error occurs during the update the LDAP error code is returned, in most case these are self explanatory and are usually due to a schema restriction.  See the Single Update option below for more information on how to determine which update caused the error.

Update Queries will update the Attributes based on the values specified in the attributes field or data specified in the Input Mode columns. To update an attribute an Update Operator must be specified after the attribute name, follow with the value you wish to set.  This is the Syntax for the update operation:

Syntax: <Attribute><Op><Value>

Attribute:  The name of the attribute that you wish to update
Op: The Update Operation that is to be performed

=+        Add Value to attribute
=-         Remove the Value from the Attribute, if no Value is specified the attribute is cleared
==        Set\Replace the current value of the attribute with Value
=|         Perform a bitwise operation of the current value of the attribute, this Op has a specific format for the Value, see mask details below
=#        Delete the object from the directory
=>        Move the object the new location specified by the Value, the Value should be encapsulated in quote marks 

Value = <Mask>:<Data>

Mask - the bitwise mask  Note: Input Mode substitution can’t be used on this field, only the data field 
Data - is the bits to be set based on the bit mask
Value - the data to be written to the attribute

The Add operator ‘=+’ can fail due of the schema definition of an attribute that is being updated.  If you use the Add operator to update an attribute that has a schema definition of single value, if there is no value assigned to the attribute the update will succeed. However, if there is a value already assigned, the update will fail.  In the case of a single value attribute its better to use the Set ‘==’ operator to assign the new value, as this will set or replace the existing value.

The value provided to update attributes can use the same substitution options that are available in the filter field i.e sid, oid, ip, ipn, idate, zdate, hex, guid, unicode, and userinput.  There is additional substitutions options for the attributes field, these are attrib and code characters.  The attrib substitution option can be used to retrieve the value of attributes on the object being updated, this is useful for updating multiple line single value attributes like the Info field.  To retrieve the value of a specific attribute, this doesn’t have to be the same attribute as the one that is being updated, you only need to specify the attribute name in the subst command i.e. {attrib:info}.  The support for the retrieval of a value is limited to attributes that only have a single value set.  If multiple values are assigned to the attribute the retrieval will fail and report an error that multiple values exist.  The substitution also supports the use of the standard C\C++ Escape characters to include control character or binary values, these are listed below.       

C\C++ Escape Characters:

\a         07        Alarm (Beep, Bell)
\b         08        Backspace
\f          0C        Formfeed
\n         0A        Newline (Line Feed); see notes below
\r          0D       Carriage Return
\t          09        Horizontal Tab
\v         0B        Vertical Tab
\\         5C       Backslash
\'          27        Single quotation mark
\"         22        Double quotation mark
\?         3F         Question mark
\hh       any       The character whose numerical value is given by hh interpreted as a hexadecimal number

The batch mode feature provides the ability to run a number of saved queries in a specified order.  It can be used to complete management tasks, one example is the automation of disabling inactive accounts.  This is achieved by creating a query that returns all accounts that are inactive based on your audit requirement, then the next query in the batch list is an update query that is configured as input query taking the results from the first query as an input, these accounts are then disabled by the second query. 

The subst option userinput can be used to prompt the user for input.  The userinput will prompt the user for an input, the input has a label which is shown on the dialog box, the label is specified in the subst command.  The user inputs are cached against the label, if a label is used a second time the cached response is used and the user is not prompted. The userinput subst can be nested in other subst options e.g. (pwdpastset>={idate:{userinput:Date}}) the user will be prompted to enter the date, then the idate subst will convert this into a 64bit date code. 

Examples:

ExtensionAttribute1==Office1                            - Sets the ExtensionAttribute1 to Office1
ProxyAddresses=+smtp:www.world.com             - Adds the value to the ProxyAddresses, the existing values are preserved
ProxyAddresses=-smtp:www.world.com              - Removes the specific value from the attribute
ProxyAddresses=-                                                 - Clear the attribute, i.e. set to not set
UserAccountControl=|2:2                                     - Sets the 2 bit of the attribute to 1
UserAccountControl=|2:0                                     - Clears the 2 bit of the attribute to 0
UserAccountControl=|6:4                                     - Clears the 2 bit and sets the 4 bit of the attribute
dn=>”cn=users,dc=domain,dc=com”                  - Move the selected object to the specified location
dn=#                                                                     - Delete the object from Active Directory
UserAccountControl=|2:##input2                         - sets bit 2 to the value of ##input2

Info=={attrib:info}\n user updated as part of change 31012
Info=={attrib:info}{attrib:mail} user updated as part of change 31012
Objectversion=={attrib:objectversion}1
Binary=+\23\34\01\5a\4f\00

The Update mode can be combined with the multi-column Input Mode to update the attributes of objects with different values.  For example if you wanted to update the department and telephone numbers for a number of users.  If you paste three columns of data into the table view containing a list of samaccountname, department name, and new telephone number and then by setting the Filter field to (samaccountname=##input) and the attribute field to Department==##input2, telephone==##input3 you can update all the users details in one operation.  Another example if you have a list of users that need to be disabled and another list of users that need to be enabled.  If you combine the list of samaccountname and in the second column specify 0 for an account you want to enable and 2 for an account you want to disable.  Pasting these columns into the table view and set the Filter field the same as with the previous example but setting the Attribute field to UserAccountControl=|2:##input2, this will update all the accounts in one operation.

Enable Updates - When selected the the update query is available 

Single Update - is the default when the Update mode is selected, this causes all the required updates to be performed as a single update operation when the query is run.  The disadvantage to using single update is if you update multiple attributes at once and one of the updates fails i.e. due to a schema restriction, the resulting error message which is reported is against the first attribute that is displayed and not the attribute that caused the update to fail.  By deselected Single Update option, each update is performed separately and if that update fails the error message is display against the attribute that caused the update to fail.

Object Deletion - the delete operator is only available when this option is selected

Delete Tree - when selected the delete operation is preformed as a delete tree operation and all sub items will also be deleted.  If this option is not selected and there are child items the delete will fail

Preview - this option is enabled by default when the Enable Updates option is selected, if the query is run with the preview options selected the returned values are the values that would be written to the attributes when the preview option is not selected.  After an update query is run the preview option is automatically selected again

Display Results - This option is used to suppress the displaying of the results, this is useful if you are updating an attribute that contains a large number of values, i.e. group memberships, and will significantly increase the performance of the update query.

Note: with the delete and move operators, the attribute used to specify the delete operator, must have a value for the operation to be executed.  The best attribute to use in this case is one that must have an attribute i.e. dn or objectclass