Active Directory Provider::Create Object

Creates a Microsoft® Active Directory® object of the specified schema class for the specified container. Used by Microsoft® Provisioning Framework (MPF).

Create Object is a wrapper for IADsContainer::Create. Create Object also uses IADs::PutEx and IADs::SetInfo to set the new object's properties and copy the object to the underlying directory store.

Currently, there is no support for setting the ntSecurityDescriptor property in this provider; however, the Script Provider can be used to create an object so that IADsSecurityDescriptor can be used.

The rollback action for Create Object is Delete Object.

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
  <container>1..1</container>
  <class>1..1</class>
  <name>1..1</name>
  <properties>0..1
	<property name=".." mode="..">0..unbounded
	<value>0..unbounded</value>
	</property>
  </properties>
  <flagIgnoreAlreadyExistsError/>0..1</flagIgnoreAlreadyExistsError>
  <flagSetOwner/>0..1</flagSetOwner>
  <autoGenerateEmailAddresses>0..1</autoGenerateEmailAddresses>
</executeData>

XML Output Schema

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

<executeData>1..1
  <path>1..1</path>
  <flagSkipAction/>0..1
</executeData>

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
autoGenerateEmailAddresses Description:
 Specifies whether Microsoft® Exchange Server 2000 is allowed to automatically generate e-mail addresses in the format "alias@domain" for new Active Directory objects that are mail-enabled. Such objects include users, groups, contacts, public folders, stores, and system attendants.

In MPF installations running Exchange 2000 Server, the default policy is to automatically generate addresses for new mail-enabled objects. When Exchange generates an address, it sets the new object's proxyAddresses property to "alias@domain". This is a problem if the object should have a different address. To override this default behavior and preserve a manually-defined value for proxyAddresses, include an autoGenerateEmailAddresses node with a value of "0" in the request to Create Object. For example:

<autoGenerateEmailAddresses>0</autoGenerateEmailAddresses>

Note  To use the autoGenerateEmailAddresses option, the computer that runs the Active Directory Provider must have Collaboration Data Objects (CDO) installed.

Parent:
executeData

class Description:
 Active Directory schema class for the new object. For example: 
<class>user</class>

Parent:
executeData

container Description:
 Lightweight directory access protocol (LDAP) path of the new object's container object. For example: 
<container>LDAP://CN=Users,DC=myDomain,DC=com</container>

If possible, allow Active Directory to dynamically assign a domain controller to the object. If you specify the domain controller in the container path, you must later use the Make Path Domain Specific procedure to modify the path so it points to the Active Directory domain instead of to the domain controller. This extra step is necessary to ensure that other domain controllers can support the object if the original controller is unavailable.

Parent:
executeData

executeData Description:
 Encapsulates the procedure's input and output data.

Children:
 autoGenerateEmailAddresses (minOccurs="0" maxOccurs="1", input only)
 class (minOccurs="1" maxOccurs="1", input only)
 container (minOccurs="1" maxOccurs="1", input only)
flagIgnoreAlreadyExists (minOccurs="0" maxOccurs="1", input only)
flagSetOwner (minOccurs="0" maxOccurs="1", input only)
flagSkipAction (minOccurs="0" maxOccurs="1", output only)
name (minOccurs="1" maxOccurs="1", input only)
path (minOccurs="1" maxOccurs="1", output only)
properties (minOccurs="0" maxOccurs="1", input only)
flagIgnoreAlreadyExistsError Description:
 Determines whether the procedure can succeed even if the object already exists. If this element is specified, the procedure ignores any errors stating that the object already exists and prevents rollback from accidentally deleting the object.

Now that MPF supports try/catch error handling (through try and catch elements), there is little need to specify flagIgnoreAlreadyExistsError. This node was originally introduced to support error handling. 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 the flagSkipAction node. Subsequent calls pass this node to prevent further operations on the object. For example, if the next call is to User Set Password, the presence of flagSkipAction prevents accidental resets of the user's password.

Parent:
executeData

flagSetOwner Description:
 Determines how the procedure sets the owner of the object. If this element is specified, the owner is set to the impersonated user or (if there is no user), the process identity.  If this element is not specified, the owner is the default owner determined by IADsContainer::Create.

Parent:
executeData

flagSkipAction Description:
Empty element returned if the object already exists and the input XML includes the flagIgnoreAlreadyExistsError element.

 

Parent:
executeData

name Description:
 Name of the new object. This name is the relative distinguished name (RDN) of the object in Active Directory. For example: 
<name>CN=myUser1</name>

Parent:
executeData

path
 		Description:
LDAP path returned for the new object. Consists of the object name and the container path. For example, inputs 
<name>CN=myUser1</name>

and

<container>LDAP://CN=Users,DC=myDomain,DC=com</container>

result in

<path>LDAP://CN=myUser1,CN=Users,DC=myDomain,DC=com</path>

path is saved in the rollback log, so it can be deleted after rollback.
properties Description:
 A list of Active Directory property names and values for the new object. For example: 
<properties>
  <property name=’sAMAccountName’>myUser1</property>
  <property name=’otherHomePhone’>
	<value>425-555-1212</value>
	<value>206-555-1212</value>
  </property>
</properties>

Parent:
executeData

Child:
 property (minOccurs="0" maxOccurs="*", input only)
property Description:
 Name of an Active Directory property for the new object. For example: 
<properties>
  <property name=’sAMAccountName’>myUser1</property>
  <property name=’otherHomePhone’>
	<value>425-555-1212</value>
	<value>206-555-1212</value>
  </property>
</properties>

Parent:
properties

Child:
 value (minOccurs="0" maxOccurs="*", input only)

Attributes:

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.
name Required. Name of the property.
value Description:
 Value for one of the object's Active Directory properties. Properties with multiple values require multiple value nodes. For example: 
<properties>
  <property name=’sAMAccountName’>myUser1</property>
  <property name=’otherHomePhone’>
	<value>425-555-1212</value>
	<value>206-555-1212</value>
  </property>
</properties>

Parent:
property

See Also

Active Directory Provider, Delete Object, Make Path Domain Specific, Make Path Domain Controller Specific, Preferred DC Active Directory Provider

Up Top of Page
© 1999-2002 Microsoft Corporation. All rights reserved.