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