Active Directory Provider::Set Properties

Sets one or more properties for an object. Used by Microsoft® Provisioning Framework (MPF).

Set Properties is a wrapper for IADs::PutEx.

XML Input Schema

The following code fragment shows the format for sending data to this procedure. For more information on individual elements and attributes, see the Elements and Attributes table.



<executeData>1..1
  <path>1..1
  <properties>1..1
	<property name=".." mode="..">1..unbounded
	<value></value>0..unbounded
	</property>
  </properties>
  <flagSkipAction>0..1</flagSkipAction>
</executeData>
XML Output Schema

Set Properties does not return data.

Elements and Attributes

The following table describes the XML schema elements and attributes. Unless otherwise indicated, the data type is string.

Element Description, relationships, and attributes
executeData Description: >
Encapsulates the procedure's input data.

Children:
flagSkipAction (minOccurs="0" maxOccurs="1")
path (minOccurs="1" maxOccurs="1")
properties (minOccurs="1" maxOccurs="1")
flagSkipAction Description:
Prevents the procedure from executing. If this element is specified, the procedure does not update object properties, even during rollback.

Now that MPF supports try/catch error handling (through try and catch elements), there is little need to specify flagSkipAction. This node was originally introduced to support error handling for Create Object. For example, a Create Object call ordinarily fails if the user already exists. To override this behavior, the request can include a flagIgnoreAlreadyExistsError node, which instructs Create Object to return a flagSkipAction node. Subsequent calls pass this node to prevent further operations on the object. In the case of Set Properties, the presence of flagSkipAction prevents accidental changes to object properties.

Parent:
executeData

path Description:
Lightweight directory access protocol (LDAP) path of the object to set properties for.

Parent:
executeData

properties Description:
List of Microsoft® Active Directory® properties to set. If there is no properties node or the element is empty, E_INVALIDARG is returned.

Parent:
executeData

Child:
property

property Description:
Individual Active Directory property.

Parent:
properties

Child:
value

Attributes:

name LDAP display name for the property.
mode Optional. Control code that indicates how the procedure handles the incoming property value.
  • "Clear": Resets the property value to "no-value".
  • " update": Replaces existing values with the new ones.
  • " append": Adds the new values to the current ones.
  • "delete": Removes the specified values.

If values are provided, the default mode is "update". If no values are provided, the default mode is "clear".

The mode attribute corresponds to ADS_PROPERTY_OPERATION_ENUM for IADs::PutEx.

ADSI currently ignores the first IADs::PutEx calls and just accepts the value from the last call. Each property node corresponds to a separate call to IADs::PutEx. If you must replace one value of a multi-valued property, do one of the following:

  • Call Get Properties and replace the value in the XML, then call Set Properties with "update" mode.
  • Call Set Properties twice. In the first call, set mode to "delete". In the second, set mode to "append".
value Description:
Value for the Active Directory property. Properties with multiple values have corresponding value nodes. A property with a single value can pass it as a text node for the property element instead of as a separate value node. Some data types, such as boolean, dateTime and bin.hex must be explicitly typed using an XML data type. This data type must reside in the immediate parent of the text node. For example: 
<value xmlns:dt='urn:schemas-microsoft-com:datatypes' dt:dt='dateTime'>2001-05-14T10:06:50.000</value>

Parent:
property

Remarks

When Set Properties is executed during rollback, it restores the original values.

 Applies To
See Also

Active Directory Provider, Preferred DC Active Directory Provider