Hosted Exchange::CreateBusinessUser
Creates a business user. The procedure will also optionally:
Set the user's password.
Make the user an admin of the organization.
Create a mailbox for the user and mail enable the user.
Arguments
Input argument | Required | Description |
---|---|---|
<container> |
Yes |
A valid Lightweight Directory Access Protocol (LDAP) path of the OU where the new user will be created. For example LDAP://OU=alpineskihouse,OU=Reseller1,OU=Hosting,DC=fabrikam,DC=Com. |
<userPrincipalName> |
Yes |
The User principal name of the user. Typically this would be <user>@<SMTPDomain> to enable UPN login to e-mail account with the user's e-mail address. |
<preferredDomainController> |
Yes |
|
<isAdmin> |
Yes |
Set this element to true if you wish the new user to be an administrator of the organization, otherwise set to false. |
<planName> |
No |
Defines which Exchange Mailbox service plan to apply to the user. |
<mailStore/@algorithm> |
No |
Possible values are "level" and "tightPack". Default is "tightPack". If this attribute is "tightPack", allocations are packed tightly to minimize the number of servers used. Otherwise, packing is leveled across mail stores. Leveling is recommended to facilitate upselling of services. |
<mailStore/serverName> |
Yes |
Specifies the target server for the new mailbox. The organization must own sufficient storage space on the server or an error is thrown. If provided the optional parameter <mailStoreName> must also be provided. |
<mailStore/mailStoreName> |
No |
Specifies the target mail store for the new mailbox. The organization must own sufficient storage space on the mail store or an error is thrown. If provided the optional parameter <serverName> must also be provided. ![]()
The procedure uses the optional <planName> element to determine whether it should create a mailbox for the user by calling Hosted Exchange::CreateMailbox.
|
<newPassword> |
No |
If present the procedure will set the new user's password with the value of this element. All domain password policy restrictions apply. |
<displayName> |
No |
|
<givenName> |
No |
|
<middleName> |
No |
|
<sn> |
No |
Surname of the user. |
<initials> |
No |
|
<description> |
No |
|
<properties> |
No |
Any valid Active Directory properties for object class user. |
<proxyAddresses> |
No |
Additional proxy addresses for the user. Ignored if planName not provided. ![]()
The procedure will accept additional proxyAddress. However, the called Hosted Exchange::CreateMailbox procedure, which is executed when a plan is specified, adds a primary SMTP address based on the user's UPN prefix and the org's SMTP Domain (e.g. user@alpineskihouse.com).
Furthermore the supplied proxyAddresses must be using a domain that has previously been assigned to the organization. |
<alias> |
No |
The procedure will accept this as an optional parameter. Other wise an alias will be generated from the UPN prefix (for example, user from user@alpineskihouse.com) |
<sAMAccountName> |
No |
Output Arguments
The <user> tag containing the user object created and the membership and security policies supplied. Each object created has its LDAP path in a "path" attribute.
If CreateMailbox was called, the <mail>, <proxyAddresses> and <properties> nodes are merged with output to show specific settings that occurred as a result of the requested service plan.
Remarks
Policy Information
Customer user.
Security
Impersonate caller.
Caller is tested for UserCreator role.
sAMAccountName Behavior
When creating a user, it is necessary to also ensure that the new user's sAMAccountName is unique within the domain. If it is not, creation will fail. Also, interactions with Exchange make it undesirable for the '@' character to appear in a sAMAccountName. Therefore, when creating or renaming a user or group, the sAMAccountName will be similar to the input name (or Universal principal name), except that illegal sAMAccountName characters are removed, and '@' characters are replaced with '_'. If the sAMAccountName collides with an existing sAMAccountName, then a random string of digits will be appended to the sAMAccountName to ensure uniqueness.
The algorithm for generating a sAMAccountName from the seed name (Universal Principal Name for a user, or cn if the object is a group), is as follows:
Remove all of the following illegal characters from the seed name: "/\[]:|<>+=;?,*
Trim the seed name to a maximum of 20 characters
If the last character is a '.', replace it with '_'
Attempt to create the object with the trial sAMAccountName
If there is a sAMAccountName collision in step 4, generate 3 trial names by limiting the seed name to 17 characters, then appending a random 3-digit number to each. Generate 2 additional trial names by limiting the seed name to 15 characters, then appending a 5-digit random number to each. Attempt to create the object using each of these 5 trial names in turn.
Sample Code
Example XML Request
<request>
<procedure>
<execute namespace="Hosted Exchange" procedure="CreateBusinessUser" impersonate="1">
<executeData>
<preferredDomainController>AD01.fabrikam.com</preferredDomainController>
<container>LDAP://OU=alpineskihouse,OU=WH,OU=Hosting,DC=fabrikam,DC=Com</container>
<userPrincipalName>admin@alpineskihouse.com</userPrincipalName>
<displayName>Bob Smith</displayName>
<givenName>Bob</givenName>
<middleName>John</middleName>
<sn>Smith</sn>
<initials>bjs</initials>
<newPassword do-not-log="1">Pass1Word</newPassword>
<description>user</description>
<planName>BaseMail</planName>
<isAdmin>true</isAdmin>
<properties>
<property name="otherHomePhone">
<value>2065551212</value>
<value>2065551213</value>
</property>
<property name="street">1703 NE 91st</property>
</properties>
</executeData>
<after source="executeData" destination="data" mode="merge"/>
</execute>
</procedure>
</request>
Extended XML Usage
Specify mailstore selection algorithm.
<request>
<procedure>
<execute namespace="Hosted Exchange" procedure="CreateBusinessUser" impersonate="1">
<executeData>
<preferredDomainController>AD01.fabrikam.com</preferredDomainController>
<container>LDAP://OU=alpineskihouse,OU=WH,OU=Hosting,DC=fabrikam,DC=Com</container>
<userPrincipalName>admin@alpineskihouse.com</userPrincipalName>
<displayName>Bob Smith</displayName>
<givenName>Bob</givenName>
<middleName>John</middleName>
<sn>Smith</sn>
<initials>bjs</initials>
<newPassword do-not-log="1">Pass1Word</newPassword>
<description>user</description>
<planName>BaseMail</planName>
<mailStore algorithm="level"/>
<isAdmin>true</isAdmin>
<properties>
<property name="otherHomePhone">
<value>2065551212</value>
<value>2065551213</value>
</property>
<property name="street">1703 NE 91st</property>
</properties>
</executeData>
<after source="executeData" destination="data" mode="merge"/>
</execute>
</procedure>
</request>Extended Usage 2 (specify a specific mailstore):
<request>
<procedure>
<execute namespace="Hosted Exchange" procedure="CreateBusinessUser" impersonate="1">
<executeData>
<preferredDomainController>AD01.fabrikam.com</preferredDomainController>
<container>LDAP://OU=alpineskihouse,OU=WH,OU=Hosting,DC=fabrikam,DC=Com</container>
<userPrincipalName>admin@alpineskihouse.com</userPrincipalName>
<displayName>Bob Smith</displayName>
<givenName>Bob</givenName>
<middleName>John</middleName>
<sn>Smith</sn>
<initials>bjs</initials>
<newPassword do-not-log="1">Pass1Word</newPassword>
<description>user</description>
<planName>BaseMail</planName>
<mailStore>
<serverName>EXBE01</serverName>
<mailStoreName>BusinessMailStore1</mailStoreName>
</mailStore>
<isAdmin>1</isAdmin>
<properties>
<property name="otherHomePhone">
<value>2065551212</value>
<value>2065551213</value>
</property>
<property name="street">1703 NE 91st</property>
</properties>
</executeData>
<after source="executeData" destination="data" mode="merge"/>
</execute>
</procedure>
</request>
Example XML Response
<response>
<data>
<preferredDomainController>AD01.fabrikam.com</preferredDomainController>
<container>LDAP://OU=alpineskihouse,OU=WH,OU=Hosting,DC=fabrikam,DC=Com</container>
<userPrincipalName>user11@alpineskihouse.com</userPrincipalName>
<displayName>Bob Smith</displayName>
<givenName>Bob</givenName>
<middleName>John</middleName>
<sn>Smith</sn>
<initials>bjs</initials>
<newPassword do-not-log="1">Pass1Word</newPassword>
<description>user</description>
<planName>GoldMail</planName>
<properties>
<property name="otherHomePhone">
<value>2065551212</value>
<value>2065551213</value>
</property>
<property name="street">
<value>1703 NE 91st</value>
</property>
<property name="msExchQueryBaseDN">OU=alpineskihouse,OU=WH,OU=Hosting,DC=fabrikam,DC=com</property>
<property name="mail">user11@alpineskihouse.com</property>
<property name="msExchMailboxFolderSet">
<value>108303</value>
</property>
<property name="showInAddressBook" mode="append">
<value>CN=Default Global Address List,CN=All Global Address Lists,CN=Address Lists Container,CN=fabrikam,CN=Microsoft Exchange,CN=Services,CN=Configuration,DC=fabrikam,DC=com</value>
</property>
<property name="msExchUserAccountControl">0</property>
</properties>
<mail>
<disablePOP>0</disablePOP>
<size>20000</size>
<disableIMAP>0</disableIMAP>
<disableHTTP>0</disableHTTP>
</mail>
<proxyAddresses>
<value>user11@alpineskihouse.com</value>
</proxyAddresses>
<user path="LDAP://cn=user11@alpineskihouse.com,OU=alpineskihouse,OU=WH,OU=Hosting,DC=fabrikam,DC=Com" name="user11@alpineskihouse.com">
<memberOfGroup name="LDAP://cn=AllUsers@alpineskihouse,cn=_Private,OU=alpineskihouse,OU=WH,OU=Hosting,DC=fabrikam,DC=com"/>
</user>
</data>
</response>
Applies To
Hosted Exchange Namespace API for:
Hosted Messaging and Collaboration version 3.5
Hosted Messaging and Collaboration version 3.0