Set-QADGroup

From PowerGUI Wiki

Jump to: navigation, search

Modify attributes of a 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

Set-QADGroup [-Identity] <IdentityParameter> [-Connection <ArsConnection>] [-ConnectionAccount <string>] [-ConnectionPassword <SecureString>] [-Control <hashtable>] [-Credential <PSCredential>] [-Description <string>] [-DeserializeValues] [-DisplayName <string>] [-Email <string>] [-ExcludedProperties <string[]>] [-GroupScope <GroupScope>] [-GroupType <GroupType>] [-IncludedProperties <string[]>] [-Keywords <UpdateStringParameter[]>] [-ManagedBy <IdentityParameter>] [-ManagerCanUpdateMembershipList <Boolean>] [-Member <UpdateIdentityParameter[]>] [-Notes <string>] [-ObjectAttributes <ObjectAttributesParameter>] [-Proxy] [-Published <Boolean>] [-RequireManagerApproval <Boolean>] [-RequireSecondaryOwnerApproval <Boolean>] [-SamAccountName <string>] [-SecondaryOwner <UpdateIdentityParameter[]>] [-SecondaryOwnersCanUpdateMembershipList <Boolean>] [-Service <string>] [-UseDefaultExcludedProperties <Boolean>] [-UseGlobalCatalog] [-Confirm] [-WhatIf] [<CommonParameters>]

Detailed Description

Use this cmdlet to change or remove values of attributes of a group in Active Directory.

The cmdlet takes a series of optional, attribute-specific parameters allowing you to make changes to attributes in Active Directory. Thus, to modify the value of the 'description' or 'displayName' attribute, you can use the -Description or -DisplayName 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.



Parameters

Name Description Required? Pipeline Input Default Value
Connection 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
Control Use this parameter to pass request controls (in-controls) to ActiveRoles Server as part of an operation request. In ActiveRoles Server, request controls are used to send extra information along with an operation request, to control how ActiveRoles Server performs the request.

The parameter value is a hash table that defines the names and values of the request controls to be passed to ActiveRoles Server. The parameter syntax is as follows:

   -Control @{<name> = <value>; [<name> = <value>] ...}

In this syntax, each of the name-value pairs is the name and the value of a single control. For instructions on how to create and use hash tables, see topic "about_associative_array" or "about_hash_tables" in Windows PowerShell Help. For information about ActiveRoles Server request controls, refer to ActiveRoles Server SDK documentation.

Note that this parameter only has an effect on the operations that are performed through ActiveRoles Server (connection established using the Proxy parameter); otherwise, this parameter causes an error condition in ActiveRoles Management Shell.

false false
Credential For parameter description, see help on the Connect-QADService cmdlet. false false
Description Set or clear the 'description' attribute. 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
DisplayName Set or clear the 'displayName' attribute. false false
Email Set or clear the 'mail' 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
GroupScope Set the group scope. Valid parameter values are: 'Global'; 'Universal'; 'DomainLocal'. false false
GroupType Set the group type. Valid parameter values are: 'Security'; 'Distribution'. false false
Identity Specify the DN, SID, GUID, or Domain\Name of the group you want to modify.

This parameter is optional since you can pipe into this cmdlet the object returned by the Get-QADGroup cmdlet, to have that object identify the group to act upon.

The first argument on the cmdlet is assumed to be the value of the -Identity parameter when no parameter name is specified.

true true (ByValue)
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
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 or an associative array that specifies one or more keywords to assign to the group or remove from the group. Some examples of possible parameter values are:

-Keywords 'keyword 1','keyword 2' Replace all the existing keywords with the keywords specified.

-Keywords @{append=@('keyword 1','keyword 2')} Add the specified keywords without removing the existing keywords.

-Keywords @{delete=@('keyword 1','keyword 2')} Remove the specified keywords, leaving the other keywords intact.

-Keywords $null Remove all the existing keywords.

This parameter has an effect only in conjunction with the Proxy connection parameter because keywords are stored and managed by ActiveRoles Server.

false false
ManagedBy Set or clear the 'managedBy' attribute. Parameter value can be the DN, SID, GUID, UPN or Domain\Name of a user or group. 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
Member Use this parameter to add or remove members from the group. Parameter value can be a string array or an associative array that specifies the identities, such as DN, SID, GUID, UPN or Domain\Name, of one or more objects to add or remove from the group. Some examples of possible parameter values are:

-Member 'domain\administrator','domain\user' Replace the existing members with the objects specified.

-Member @{append=@('domain\administrator','domain\user')} Add the specified objects to the group.

-Member @{delete=@('domain\administrator','domain\user')} Remove the specified objects from the group.

-Member $null Remove all members from the group.

Note that this parameter only makes changes to the 'member' attribute, and has no effect on the group members that have the group set as the primary group.

false false
Notes Set or clear the 'info' attribute. 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='Associates';extensionAttribute2='Paris'} array to the ObjectAttributes parameter causes the cmdlet to set 'Notes' to 'Associates' and 'Custom Attribute 2' to 'Paris' on the group.

For information about associative arrays, type the following command at the PowerShell command-prompt:

help about_associative_array

false true (ByValue, ByPropertyName)
Proxy For parameter description, see help on the Connect-QADService cmdlet. false false
Published Set the 'edsvaPublished' attribute to this parameter value. The attribute determines whether the group is published to ActiveRoles Self-Service Manager. When the attribute is set to $true, the group is published, which enables self-service users to submit requests to join or leave that group. This parameter has an effect only in conjunction with the Proxy connection parameter because the group publication status is stored and managed by ActiveRoles Server. false false
RequireManagerApproval Set the 'edsvaApprovalByPrimaryOwnerRequired' attribute to this parameter value. 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. 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
SamAccountName Set or clear the 'sAMAccountName' attribute. false false
SecondaryOwner Use this parameter to add or remove secondary owners. Parameter value can be a string array or an associative array that specifies the identifiers, such as DN, SID, GUID, UPN or Domain\Name, of one or more users or groups to add or remove from the secondary owner role. Some examples of possible parameter values are:

-SecondaryOwner 'domain\administrator','domain\user' Replace the existing identities in the secondary owners list with the identities specified.

-SecondaryOwner @{append=@('domain\administrator','domain\user')} Add the specified identities to the secondary owners list, without removing the existing owners.

-SecondaryOwner @{delete=@('domain\administrator','domain\user')} Remove the specified identities from the secondary owners list, leaving the other owners intact.

-SecondaryOwner $null Clear the secondary owners list, so that no secondary owners are specified.

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
SecondaryOwnersCanUpdateMembershipList Not Specified false false
Service For parameter description, see help on the Connect-QADService 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
UseGlobalCatalog For parameter description, see help on the Connect-QADService cmdlet. false false
Confirm Prompts you for confirmation before executing the command. false false
WhatIf Describes what would happen if you executed the command without actually executing the command. false false

Examples

EXAMPLE 1

set-QADGroup 'MyDomain\AMS Managers' -description 'Amsterdam Managers'

Description


Connect to any available domain controller with the credentials of the locally logged on user, bind to a specific group by Domain\Name, and modify the description of the group.

EXAMPLE 2

set-QADGroup '<DN of group object>' -Service 'server.domain.local:389' -description 'My AD LDS group object'

Description


Connect to the AD LDS instance on 'server.domain.local:389' with the credentials of the locally logged on user, bind to a specific AD LDS group object by DN, and modify the description of the AD LDS group object.

EXAMPLE 3

Get-QADGroup MyTestGroup |	
 %{Set-QADGroup $_ -SamAccountName ($_.SamAccountName + "New")}

Description


Pipe the get-QADGroup output into the setQADGroup cmdlet to change the pre-Windows 2000 group name (add the "New" suffix to the name of the group returned by getQADGroup).

EXAMPLE 4

set-QADGroup 'CN=TestGroup,OU=Groups,DC=domain,DC=company,DC=com' -samaccountname 'My Test Group'

Description


Bind to the group by distinguished name and set the group name (pre-Windows 2000).

Personal tools