AddUser (OP-02)

Request and response

Part	Type	Description
inUserId	String	The new account's SamAccountName and DisplayName.
inPassword	String	The initial password. When empty, a hard-coded default literal is substituted (BR-10) — the value is never reproduced in this documentation.
inName	String	The account's Name property.
inGivenName	String	The account's GivenName property.
inSurName	String	The account's Surname property.
inDescription	String	The account's Description property.
inPhoneNum	String	Written to telephoneNumber only when non-empty (BR-13).
inMailAddr	String	Written to mail only when non-empty.
inTitle	String	Written to title only when non-empty.
inInfo	String	Written to info only when non-empty.
inCompany	String	Written to company only when non-empty.
inFAXNum	String	Written to facsimileTelephoneNumber only when non-empty.
inDivision	String	Written to division only when non-empty.

Part	Type	Description
<return>	ADServiceResponse	Response is Success, Failure, or AccessDenied's Failure. Message carries the caught exception text on a Failure, otherwise empty.

WebMethod attributes

<WebMethod()> — bare, no arguments supplied.

Steps

1. CheckAccess(); if HasAccess is False, return AccessDenied() (BR-01).
2. Compute the target container "CN=Users," & CONTAINER_EXT (BR-09).
3. Call H1 GetContext for the external domain; the result is discarded and rebuilt at step 6.
4. Initialize the response sentinel to Success with an empty message.
5. Call H2 GetUserPrincipal for the external domain to test for an existing account.
6. If a principal is found, set Response = UserExists, then immediately overwrite it with Response = Failure, and skip to step 13 (BR-12) — the UserExists code is assigned but never reaches the wire (tech debt TD-17, see Tech debt).
7. Otherwise rebuild the context scoped to the target container and construct New UserPrincipal(prinContext).
8. If inPassword is empty, substitute the hard-coded default password literal (BR-10) — the literal is a known shared credential and is never reproduced in this documentation (see Authentication and authorization and Tech debt).
9. Populate GivenName, Surname, DisplayName = inUserId, Name = inName, SamAccountName = inUserId, SetPassword(inPassword), ScriptPath = " ", Description, and Enabled = True (BR-11).
10. userPrin.Save() inside Try.
11. On exception, set Response = Failure, Message = ex.Message — and continue into the DirectoryEntry block below, operating on an unsaved principal (tech debt TD-18, HIGH — see Tech debt).
12. When the underlying object is a DirectoryEntry, write company, telephoneNumber, mail, info, title, facsimileTelephoneNumber, and division, each only when the matching input is non-empty (BR-13).
13. dirEntry.CommitChanges() inside Try.
    • On exception, set Response = Failure, Message = ex.Message.
14. Finally releases userPrin, prinContext, and dirEntry.
15. Return the response sentinel.

Process flow

flowchart TD
    A["Call AddUser"] --> B{"CheckAccess<br>HasAccess?"}
    B -->|"No"| C["Return AccessDenied<br>Failure"]
    B -->|"Yes"| D["Build CN=Users container path"]
    D --> E["GetUserPrincipal<br>test existence"]
    E -->|"Found"| F["Set UserExists<br>then overwrite Failure"]
    F --> M["Return response"]
    E -->|"Not found"| G["Rebuild context<br>scoped to container"]
    G --> H["New UserPrincipal<br>substitute default password if empty"]
    H --> I["Populate account fields<br>Enabled = True"]
    I --> J["userPrin.Save<br>in Try/Catch"]
    J --> K["Write optional<br>directory attributes"]
    K --> L["dirEntry.CommitChanges<br>in Try/Catch"]
    L --> M

Shared state effects

None — this operation touches no process-wide state; all locals are per-request.

Error handling

The operation returns a sentinel ADServiceResponse for every outcome inside the two Try blocks (Save, CommitChanges). A framework SOAP fault is possible only for a failure outside those blocks — context construction, New UserPrincipal, or a property assignment. See Faults for the service-wide fault model.

Authorization

Gated by BR-01: the caller must pass the IP allow-list check enforced by CheckAccess. See Authentication and authorization.

Related documentation

• Service index
• Overview
• Architecture
• Activation and hosting
• Operations
• Operations and processes
• Business rules
• Authentication and authorization
• Configuration
• Dependencies
• Faults
• Operational runbook
• Tech debt

Sources

• src\ADUserServices\clsADUserServices.asmx.vb (lines 91-197)