New-QADGroup
From PowerGUI Wiki
Create a new group in Active Directory. Supported are both Active Directory Domain Services (AD DS) and Active Directory Lightweight Directory Services (AD LDS).
This cmdlet is part of the Quest ActiveRoles Server product. Use Get-QARSProductInfo to view information about ActiveRoles Server.
Contents |
Syntax
New-QADGroup -ParentContainer <IdentityParameter> [-Name] <String> [-Member <IdentityParameter[]>] [-Keywords <String[]>] [-SecondaryOwner <IdentityParameter[]>] [-SamAccountName <String>] [-ManagedBy <IdentityParameter>] [-Notes <String>] [-Email <String>] [-GroupType <GroupType>] [-GroupScope <GroupScope>] [-RequireManagerApproval [<Boolean>]] [-RequireSecondaryOwnerApproval [<Boolean>]] [-ManagerCanUpdateMembershipList [<Boolean>]] [-SecondaryOwnersCanUpdateMembershipList [<Boolean>]] [-Published [<Boolean>]] [-ObjectAttributes <ObjectAttributesParameter>] [-Description <String>] [-DisplayName <String>] [-ExcludedProperties <String[]>] [-IncludedProperties <String[]>] [-DeserializeValues] [-UseDefaultExcludedProperties [<Boolean>]] [-Proxy] [-UseGlobalCatalog] [-Service <String>] [-ConnectionAccount <String>] [-ConnectionPassword <SecureString>] [-Credential <PSCredential>] [-Connection <ArsConnection>] [-WhatIf] [-Confirm] [<CommonParameters>]
Detailed Description
Use this cmdlet to create a group in Active Directory and, optionally, add members to and set other attribute values in the newly created group.
This cmdlet takes a series of optional, attribute-specific parameters allowing you to set attributes in the newly created group. Thus, to set the value of the 'description', 'displayName', or 'member' attribute, you can use the -Description, -DisplayName, or -Member parameter, respectively.
If a given attribute is referred to by both the ObjectAttributes array and an attribute-specific parameter, the ObjectAttributes setting has no effect on that attribute. The cmdlet sets the attribute to the value specified by the attribute-specific parameter.
The cmdlet has optional parameters that determine the server and the security context for the operation. Normally, the connection parameters could be omitted so far as a connection to a server is established prior to using the cmdlet. In this case, the server and the security context are determined by the Connect-QADService cmdlet.
If you do not use Connect-QADService and have no connection established prior to using a cmdlet, then the connection settings, including the server and the security context, are determined by the connection parameters of the first cmdlet you use. Subsequent cmdlets will use those settings by default.
Related Commands
Parameters
| Name | Description | Required? | Pipeline Input | Default Value |
|---|---|---|---|---|
| ParentContainer | Specify the distinguished name (DN) of the container in which you want this cmdlet to create a new group. | true | true (ByPropertyName) | |
| Name | Specify the name (CN) for the new group to be created. | true | true (ByValue, ByPropertyName) | |
| Member | Set the value of the 'member' attribute. | false | false | |
| Keywords | Use this parameter to supply keywords for the group. Keywords are words or phrases that could help users find the group in ActiveRoles Server client applications, such as ActiveRoles Self-Service Manager. Parameter value can be a string array that specifies one or more keywords to assign to the group. This parameter has an effect only in conjunction with the Proxy connection parameter because keywords are stored and managed by ActiveRoles Server. | false | false | |
| SecondaryOwner | Set the 'edsvaSecondaryOwners' attribute. Supply the DN, SID, GUID, UPN or Domain\Name of the user or group to be set as a secondary owner. You can supply a string array of object identifiers to specify several secondary owners. This parameter has an effect only in conjunction with the Proxy connection parameter because the secondary owner settings are stored and managed by ActiveRoles Server. | false | false | |
| SamAccountName | Specify the pre-Windows 2000 group name for the new group to be created. | false | false | |
| ManagedBy | Specify the DN, SID, GUID, UPN or Domain\Name of the user or group to be set as the 'managedBy' attribute value on the object in the directory. | false | false | |
| Notes | Set the 'info' attribute to this parameter value. | false | false | |
| Set the 'mail' attribute to this parameter value. | false | false | ||
| GroupType | Specify the type of the new group to be created. Acceptable values: 'Security'; 'Distribution'. If this parameter is omitted, the cmdlet assumes that GroupType is set to 'Security'. | false | false | Security |
| GroupScope | Specify the scope of the new group to be created. Acceptable values: 'Global'; 'Universal'; 'DomainLocal'. If this parameter is omitted, the cmdlet assumes that GroupScope is set to 'Global'. | false | false | Global |
| RequireManagerApproval | Set the 'edsvaApprovalByPrimaryOwnerRequired' attribute to this parameter value ($true or $false). The attribute determines whether changes to the members list of a group require approval by the primary owner (manager) of that group. This parameter has an effect only in conjunction with the Proxy connection parameter because the approval settings are stored and managed by ActiveRoles Server. | false | false | |
| RequireSecondaryOwnerApproval | Set by the 'edsvaApprovalBySecondaryOwnerRequired' attribute to this parameter value ($true or $false). The attribute determines whether changes to the members list of a group require approval by a secondary owner of that group. This parameter has an effect only in conjunction with the Proxy connection parameter because the approval settings are stored and managed by ActiveRoles Server. | false | false | |
| ManagerCanUpdateMembershipList | Use this parameter to specify whether the manager (primary owner) of the group is allowed to add or remove members from that group. Supply the parameter value of $true if you want to allow the manager to add or remove group members; supply the parameter value of $false to configure the group so that its manager is not allowed to add or remove group members. This parameter requires a connection to ActiveRoles Server, and therefore it should be used in conjunction with the Proxy connection parameter. | false | false | |
| SecondaryOwnersCanUpdateMembershipList | Use this parameter to specify whether secondary owners of the group are allowed to add or remove members from that group. Supply the parameter value of $true if you want to allow the secondary owners to add or remove group members; supply the parameter value of $false to configure the group so that its secondary owners are not allowed to add or remove group members. This parameter requires a connection to ActiveRoles Server, and therefore it should be used in conjunction with the Proxy connection parameter. | false | false | |
| Published | Supply this parameter if you want to publish the group to ActiveRoles Self-Service Manager. Publishing a group enables self-service users to submit requests to join or leave that group. | false | false | |
| ObjectAttributes | Specify an associative array that defines the attributes to set. The array syntax:
@{attr1='val1';attr2='val2';...} In this syntax, each of the key-value pairs is the LDAP display name and the value of an attribute to set. Thus, passing the @{info=;description='Admins'} array to the ObjectAttributes parameter causes the cmdlet to clear the 'Notes' attribute and set the 'Description' attribute to 'Admins'. For information about associative arrays, type the following command at the PowerShell command-prompt: help about_associative_array | false | true (ByValue, ByPropertyName) | |
| Description | Set the value of the 'description' attribute. | false | false | |
| DisplayName | Set the value of the 'displayName' attribute. | false | false | |
| ExcludedProperties | Use this parameter to specify the attributes that you do not want the cmdlet to update in the directory. Supply a list of the attribute LDAP display names as the parameter value. You could use this parameter when importing attribute values from a text file, in order to prevent some attributes found in the file from being set in the directory. | false | false | |
| IncludedProperties | Use this parameter to specify explicitly the attributes that you want the cmdlet to update in the directory. Supply a list of the attribute LDAP display names as the parameter value. When used together with UseDefaultExcludedProperties, this parameter allows you to have the cmdlet update some attributes that would not be updated otherwise.
Note: If a particular attribute is listed in both ExcludedProperties and IncludedProperties, the cmdlet does not set the value of that attribute the directory. | false | false | |
| DeserializeValues | Supply this parameter on the command line if the input you pass to the cmdlet contains serialized attribute values (for instance, when importing a directory object from a text file that was created using the Serialize parameter). For examples of how to export and import an object, see help on the Get-QADUser cmdlet. | false | false | |
| UseDefaultExcludedProperties | When set to 'true', this parameter causes the cmdlet not to update a certain pre-defined set of attributes in the directory. This pre-defined set of attributes (referred to as "default excluded properties") can be viewed or modified by using the Get-QADPSSnapinSettings or Set-QADPSSnapinSettings cmdlet, respectively. | false | false | false |
| Proxy | For parameter description, see help on the Connect-QADService cmdlet. | false | false | |
| UseGlobalCatalog | For parameter description, see help on the Connect-QADService cmdlet. | false | false | |
| Service | For parameter description, see help on the Connect-QADService cmdlet. | false | false | |
| ConnectionAccount | For parameter description, see help on the Connect-QADService cmdlet. | false | false | |
| ConnectionPassword | For parameter description, see help on the Connect-QADService cmdlet. | false | false | |
| Credential | For parameter description, see help on the Connect-QADService cmdlet. | false | false | |
| Connection | For parameter description, see help on the Connect-QADService cmdlet. | false | false | |
| WhatIf | Describes what would happen if you executed the command, without actually executing the command. | false | false | |
| Confirm | Prompts you for confirmation before executing the command. | false | false |
Examples
Example 1
new-qadGroup -ParentContainer 'OU=companyOU,DC=company,DC=com' -name 'group1' -samAccountName 'group1' -grouptype 'Distribution' -groupscope 'Universal'
Connect to any available domain controller with the credentials of the locally logged on user, and create a new universal distribution group.
Example 2
$pw = read-host "Enter password" -AsSecureString C:\PS>connect-qadService -service 'localhost' -proxy -ConnectionAccount 'company\administrator' -ConnectionPassword $pw C:\PS>new-qadGroup -ParentContainer 'OU=companyOU,DC=company,DC=com' -name 'group1' -samAccountName 'group1' -grouptype 'Distribution' -groupscope 'Universal' C:\PS>disconnect-qadService
Connect to the local Administration Service with the credentials of a specific user, create a new universal distribution group, and then disconnect.
Example 3
$pw = read-host "Enter password" -AsSecureString
C:\PS>connect-qadService -service 'localhost' -proxy -ConnectionAccount 'company\administrator' -ConnectionPassword $pw
C:\PS>import-csv C:\temp\data.csv | %{new-qadGroup -ParentContainer 'OU=companyOU,DC=company,DC=com' -name $_.'group name' -samAccountName $_.'group name'}
C:\PS>disconnect-qadService
Connect to the local Administration Service with the credentials of a specific user, import a CSV file, for each record in the file create a new global security group with the name matching the value in the 'group name' column in the CSV file, and then disconnect.
Example 4
new-QADGroup -Service 'server.domain.local:389' -Name 'group1' -ParentContainer '<DN of container>'
Connect to the AD LDS instance on 'server.domain.local:389' with the credentials of the locally logged on user, and create a new AD LDS group in a certain container.
