New-ADOrganizationalUnit

Create a new Active Directory organizational unit.

Syntax
      New-ADOrganizationalUnit [-Name] string
         [-AuthType {Negotiate | Basic}] [-City string] [-Country string]
            [-Credential PSCredential] [-Description string]
               [-DisplayName string] [-Instance ADOrganizationalUnit]
                  [-ManagedBy ADPrincipal] [-OtherAttributes hashtable]
                     [-PassThru] [-Path string] [-PostalCode string] [-ProtectedFromAccidentalDeletion bool]
                        [-Server string] [-State string] [-StreetAddress string]
                           [-Confirm] [-WhatIf] [CommonParameters]

Key
   -AuthType {Negotiate | Basic}
       The authentication method to use: Negotiate (or 0), Basic (or 1)
       A Secure Sockets Layer (SSL) connection is required for Basic authentication.

   -City string
       The user's town or city.
        
    -Country string
       The country or region code for the user's language of choice.
       The LDAP Display Name (ldapDisplayName) of this property is "c".

   -Credential PSCredential
       The user account credentials to use to perform this task.
       The default credentials are those of the currently logged on user unless the
       cmdlet is run from an Active Directory PowerShell provider drive.
       If the cmdlet is run from such a provider drive, the account associated with the drive is the default.

       Type a user name, such as "User64" or "Domain64\User64" or specify a
       PSCredential object such as one generated by Get-Credential 

       If a user name is specified, the cmdlet will prompt for a password.

   -Description string
       A description of the object.

   -DisplayName string
       The display name of the object.

   -Instance ADOrganizationalUnit
       An instance of a organizational unit object to use as a template for a new OU object.

       Use an instance of an existing OU object as a template or construct a
       new OU object by using the PowerShell command line or by using a script.

       The following examples show how to use these two methods:

       Method 1: Use the Get-ADOrganizationalUnit cmdlet and then override property values of
       the new object by setting the appropriate parameters. 

          $ouInstance = Get-ADOrganizationalUnit -Identity demoOU1
          New-ADOrganizationalUnit -Name demo2  -Instance $ouInstance -Country Canada

       Method 2: Use the New-ADOrganizationalUnit cmdlet and pass this object to the -Instance
       parameter of New-ADOrganizationalUnit to create the new AD OU object.

          $ouInstance = new-object Microsoft.ActiveDirectory.Management.ADOrganizationalUnit
          $ouInstance.Country = Canada
          New-ADOrganizationalUnit -Name accountingCanada  -Instance $ouInstance

       Note: Specified attributes are not validated, so attempting to set attributes that
             do not exist or cannot be set will raise an error.

   -ManagedBy ADPrincipal
       The user or group that manages the object by providing one of the following property values.
       Note: The identifier in parentheses is the LDAP display name for the property.
          Distinguished Name 
            Example:  CN=demo1,OU=Europe,CN=Users,DC=corp,DC=ss64,DC=com
          GUID (objectGUID) 
            Example: 599c3d2e-f72d-4d20-8a88-030d99495f20 
          Security Identifier (objectSid) 
            Example: S-1-5-64-3265277888-301567356-523410843-1244
          SAM Account Name (sAMAccountName) 
            Example: demo1

   -Name string
       The name of the object. 
    
   -OtherAttributes hashtable
       Object attribute values for attributes that are not represented by cmdlet parameters.
       Set one or more parameters at the same time with this parameter.
       If an attribute takes more than one value, you can assign multiple values.
       To identify an attribute, specify the LDAPDisplayName (ldapDisplayName) defined for it in
       the Active Directory schema.

        Syntax:
        To specify a single value for an attribute:
           -OtherAttributes @{'AttributeLDAPDisplayName'=value}
        To specify multiple values for an attribute
           -OtherAttributes @{'AttributeLDAPDisplayName'=value1,value2,...}

        Specify values for more than one attribute by using semicolons to separate attributes.
        To set values for multiple attributes:
           -OtherAttributes @{'Attribute1LDAPDisplayName'=value; 'Attribute2LDAPDisplayName'=value1,value2;...}

        The following examples show how to use this parameter.

        To set the value of a custom attribute called favColors that takes a set of Unicode strings: 
           -OtherAttributes @{'favColors'="pink","purple"}

        To set values for favColors and dateOfBirth simultaneously, use the following syntax:
           -OtherAttributes @{'favColors'="pink","purple"; 'dateOfBirth'=" 01/01/1960"}

   -PassThru switch
       Return the new or modified object.
       By default (i.e. if -PassThru is not specified), this cmdlet does not generate any output.
        
   -Path string
       The X.500 path of the Organizational Unit (OU) or container where the new object is created.  

       In many cases, a default value will be used for -Path if no value is specified.

       Note:  The PowerShell cmdlets, such New-Item, Remove-Item, Remove-ItemProperty, Rename-Item and 
       Set-ItemProperty also contain a Path property. However, for the AD provider cmdlets, the -Path parameter 
       identifies the path of the actual object and not the container.

   -PostalCode string
       The user's postal code or zip code.

   -ProtectedFromAccidentalDeletion bool
       Whether to prevent the object from being deleted.
       When this property is set to true, you cannot delete the corresponding object without
       first changing the value of this property.
       Possible values: $false or 0, $true or 1

   -Server string
       The AD Domain Services instance to connect to, this may be a Fully qualified domain name,
       NetBIOS name, Fully qualified directory server name (with or without port number)

   -State string
       The user's or Organizational Unit's state or province.
        
   -StreetAddress string
       The organizational unit's street address.

   -Confirm
       Prompt for confirmation before executing the command.

   -WhatIf
       Describe what would happen if you executed the command without actually executing the command.

   CommonParameters:
       -Verbose, -Debug, -ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
       -OutBuffer -OutVariable.

New-ADOrganizationalUnit cmdlet creates a new AD OU. Commonly used organizational unit property values may be set using the cmdlet parameters. Property values that are not associated with cmdlet parameters can be set by using the -OtherAttributes parameter.

You must set the -Name parameter to create a new organizational unit.
If the -Path parameter is not specified, the cmdlet creates an organizational unit under the default NC head for the domain.

There are 3 different ways to create an OU object.

Method 1: Use the New-ADOrganizationalUnit cmdlet, specify the required parameters, and set any additional property values by using cmdlet parameters.

Method 2: Use a template to create the new object. Create (or retrieve) an OU object and set the -Instance parameter to this object. The object provided to the -Instance parameter will then used as a template for the new object. Property values from the template may be overridden by setting cmdlet parameters.

Method 3: Pass objects through the pipeline from Import-CSV to New-ADOrganizationalUnit to create multiple AD OU objects.

Examples

Create a new OU named 'Laptops' which is protected from accidental deletion.:

PS C:\> New-ADOrganizationalUnit -Name Laptops -Path "DC=SS64,DC=COM"

Create an OU named 'EAME', protected from accidental deletion and set its 'seeAlso' and 'managedBy' properties:

PS C:\> New-ADOrganizationalUnit -Name EAME -Path "DC=SS64,DC=COM" -OtherAttributes @{seeAlso="CN=Asia,OU=Groups,OU=Managed,DC=SS64,DC=com";managedBy="CN=KenC,DC=SS64,DC=COM"}

Uses the data from one OU as a template for another new OU:

PS C:\> $ouTemplate = Get-ADOrganizationalUnit "OU=EAME,DC=SS64,DC=com" -properties seeAlso,managedBy
PS C:\> New-ADOrganizationalUnit -name KenCReports -instance $ouTemplate

“Never be afraid to try something new. Remember, amateurs built the ark. Professionals built the Titanic” ~ Unknown Author

Related:

Get-adOrganizationalUnit - Get one or more AD OUs
Remove-adOrganizationalUnit - Remove an AD OU
Set-adOrganizationalUnit - Modify an AD OU


© Copyright SS64.com 1999-2013
Some rights reserved