Get-QADManagedObject

From PowerGUI Wiki

Jump to: navigation, search

Retrieve objects for which a particular user, contact or group is the manager (primary owner) or a secondary owner.

This cmdlet is part of the Quest ActiveRoles Server product. Use Get-QARSProductInfo to view information about ActiveRoles Server.

Contents

Syntax

Get-QADManagedObject [-Identity] <IdentityParameter> [-Activity <string>] [-Anr <string>] [-Connection <ArsConnection>] [-ConnectionAccount <string>] [-ConnectionPassword <SecureString>] [-ConsiderInheritedOwnership] [-ConsiderSecondaryOwnership] [-Control <hashtable>] [-CreatedAfter <DateTime>] [-CreatedBefore <DateTime>] [-CreatedOn <DateTime>] [-Credential <PSCredential>] [-Description <string[]>] [-DisplayName <string[]>] [-DontConvertValuesToFriendlyRepresentation] [-DontUseDefaultIncludedProperties] [-ExcludedProperties <string[]>] [-IncludeAllProperties] [-IncludedProperties <string[]>] [-LastChangedAfter <DateTime>] [-LastChangedBefore <DateTime>] [-LastChangedOn <DateTime>] [-LdapFilter <string>] [-Name <string[]>] [-PageSize <int>] [-ProgressThreshold <int>] [-Proxy] [-ReturnPropertyNamesOnly] [-SearchAttributes <Object>] [-SerializeValues] [-Service <string>] [-ShowProgress] [-SizeLimit <int>] [-Type <string>] [-UseDefaultExcludedProperties <Boolean>] [-UseDefaultExcludedPropertiesExcept <string[]>] [-UseGlobalCatalog] [-WildcardMode <WildcardMode>] [<CommonParameters>]

Detailed Description

For a particular identity (user, group or contact), you can use this cmdlet to search an Active Directory domain or container for directory objects such as groups, computers or organizational units that:

- Have the given identity designated as the manager in Active Directory
  (the identity is specified in the managedBy attribute of the object)
- Have the given identity designated as a secondary owner in ActiveRoles Server
  (the identity is specified in the edsvaSecondaryOwners attribute of the object)
- Have a group designated as the manager, with the given identity belonging
  to that group (so the identity inherits the manager role from the group)
- Have a group designated as a secondary owner, with the given identity belonging
  to that group (so the identity inherits the secondary owner role from the group)

In ActiveRoles Server, the identity that is designated as the manager of an object is referred to as the primary owner of that object. The primary owner role may also be inherited from a group that is designated as the manager. The cmdlet allows you to retrieve the objects for which a particular identity holds the owner role, whether primary, secondary, or both. It is possible to specify whether you want the search results to include the objects for which the given identity inherits the owner role from a group.

By default, the cmdlet searches for only the objects that have the specified identity designated as the manager in Active Directory. You can broaden the search by using the ConsiderSecondaryOwnership or ConsiderInheritedOwnership parameter.

The output of the cmdlet is a collection of objects, with each object representing one of the directory objects found by the cmdlet. You can pipe the output into another cmdlet, such as Set-QADObject, to make changes to the directory objects returned by this cmdlet.

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
Activity Use this parameter to specify the line of text above the progress bar which the cmdlet displays to depict the status of the running command in case of a lengthy operation. This text describes the activity whose progress is being reported (see also ShowProgress and ProgressThreshold). If this parameter is omitted, the name of the cmdlet is displayed above the progress bar. false false
Anr Specify a value to be resolved using ambiguous name resolution (ANR). Which attributes are included in an ANR search depends upon the Active Directory schema. Thus, in Windows Server 2003 based Active Directory, the following attributes are set for ANR by default:
Display-Name (displayName) 
Given-Name (givenName) 
Legacy-Exchange-DN (legacyExchangeDN) 
ms-DS-Additional-Sam-Account-Name (msDS-AdditionalSamAccountName) 
Physical-Delivery-Office-Name (physicalDeliveryOfficeName) 
Proxy-Addresses (proxyAddresses) 
RDN (name) 
SAM-Account-Name (sAMAccountName) 
Surname (sn) 

For instance, when you supply 'ann*' as the value of this parameter, the cmdlet searches for objects that have ann at the beginning of the value of at least one of the attributes listed above.

false false
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
ConsiderInheritedOwnership This parameter causes the cmdlet to retrieve the objects for which the given identity inherits the owner role from a group that is assigned as an owner. Without this parameter, the cmdlet retrieves only the objects for which the identity itself is assigned as an owner (that is, specified in the 'managedBy' or 'edsvaSecondaryOwners' attribute of the object).

This parameter requires a connection to ActiveRoles Server, and therefore it should be used in conjunction with the Proxy connection parameter.

false false
ConsiderSecondaryOwnership This parameter causes the cmdlet to retrieve the objects for which the given identity is a manager (primary owner) or secondary owner. Without this parameter, the cmdlet retrieves only the objects for which that identity is a manager (primary owner).

This parameter requires a connection to ActiveRoles Server, and therefore it should be used in conjunction with the Proxy connection parameter.

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
CreatedAfter Specify the lower boundary of the object creation date and time by which to filter objects found. The cmdlet returns only the objects that were created after the date and time specified. Supplying both CreatedAfter and CreatedBefore bounds a time interval for the objects' creation. If you supply only CreatedAfter, there is no upper boundary on the date. Parameter value is a DateTime object that specifies the date and time you want. false false
CreatedBefore Specify the upper boundary of the object creation date and time by which to filter objects found. The cmdlet returns only the objects that were created before the date and time specified. Supplying both CreatedAfter and CreatedBefore bounds a time interval for the objects' creation. If you supply only CreatedBefore, there is no lower boundary on the date. Parameter value is a DateTime object that specifies the date and time you want. false false
CreatedOn Specify the object creation date by which to filter objects found, searching for objects created within the date specified. This parameter is mutually exclusive with the CreatedAfter and CreatedBefore parameters. Parameter value is a DateTime object that specifies the date you want. false false
Credential For parameter description, see help on the Connect-QADService cmdlet. false false
Description Search by the 'description' attribute. false false
DisplayName Search by the 'displayName' attribute. false false
DontConvertValuesToFriendlyRepresentation This parameter causes the cmdlet to represent the Integer8 and OctetString attribute values "as is," without converting them to a user-friendly, human-readable form. If this parameter is omitted, the cmdlet performs the following data conversions:
- The values of the Integer8 attributes listed in the 
  Integer8AttributesThatContainDateTimes array 
  (see the parameter descriptions for the 
  Get-QADPSSnapinSettings and Set-QADPSSnapinSettings
  cmdlets) are converted from IADsLargeInteger to DateTime
- The values of the Integer8 attributes listed in the 
  Integer8AttributesThatContainNegativeTimeSpans array 
  (see the parameter descriptions for the 
  Get-QADPSSnapinSettings and Set-QADPSSnapinSettings
  cmdlets) are converted from IADsLargeInteger to TimeSpan
- The values of the other Integer8 attributes are 
  converted from IADsLargeInteger to Int64
- The values of the OctetString attributes are converted
  from byte[] to BinHex strings

Note: This parameter has an effect only on the properties of the output object that have the member type of NoteProperty. Such properties are normally added to the output object in order to provide access to the attribute values of the respective directory object that are loaded to the local memory cache but cannot be accessed by using properties of the base object (the object for which the output object serves as a wrapper).

false false
DontUseDefaultIncludedProperties This parameter causes the cmdlet to load only a small set of attributes from the directory to the local memory cache (normally, this set is limited to objectClass and ADsPath). Other attributes are retrieved from the directory as needed when you use the cmdlet's output objects to read attribute values. Thus, if you want only to count the objects that meet certain conditions (rather than examine values of particular attributes), then you can use this parameter to increase performance of your search. For examples of how to use this parameter, see help on the Get-QADUser cmdlet.

Note: If a cmdlet does not cache a particular attribute, then the output object returned by the cmdlet may not have a property that would provide access to the value of the attribute.

false false
ExcludedProperties Use this parameter to specify the attributes that you do not want the cmdlet to retrieve from the directory and store in the memory cache on the local computer. Supply a list of the attribute LDAP display names as the parameter value. By default, the cmdlet caches a certain pre-defined set of attributes, which you can view or modify by using the Get-QADPSSnapinSettings or Set-QADPSSnapinSettings cmdlet, respectively. Using the ExcludedProperties parameter you can change this default behavior on an ad-hoc basis, in order to prevent certain attributes from being loaded. Another scenario involves the use of this parameter in conjunction with IncludeAllProperties in order to restrict the set of the cached attributes.

Note: If a cmdlet does not cache a particular attribute, then the output object returned by the cmdlet may not have a property that would provide access to the value of the attribute.

false false
Identity Specify the Distinguished Name (DN), Canonical Name, GUID, Domain\Name, UPN or SID of a user, group or contact. The cmdlet searches for the objects for which the specified user, group or contact is the manager (primary owner) or a secondary owner. true true (ByValue)
IncludeAllProperties With this parameter, the cmdlet retrieves all attributes of the respective directory object (such as a User object), and stores the attribute values in the memory cache on the local computer. Attribute values can be read from the memory cache by using properties of the object returned by the cmdlet. Thus, when used in conjunction with the SerializeValues parameter, it allows an entire object to be exported from the directory to a text file. For examples of how to use this parameter, see help on the Get-QADUser or Get-QADObject cmdlet. false false
IncludedProperties Use this parameter to specify the attributes that you want the cmdlet to retrieve from the directory and store in the memory cache on the local computer. Supply a list of the attribute LDAP display names as the parameter value. By default, the cmdlet caches a certain pre-defined set of attributes, which you can view or modify by using the Get-QADPSSnapinSettings or Set-QADPSSnapinSettings cmdlet, respectively. Using the IncludedProperty parameter you can direct the cmdlet to cache some attributes in addition to the default set.

Note: Caching an attribute guarantees that the value of the attribute can be read by using properties of the output object returned by the cmdlet.

false false
LastChangedAfter Specify the lower boundary of the object modification date and time by which to filter objects found. The cmdlet returns only the objects that have last changed after the date and time specified. Supplying both LastChangedAfter and LastChangedBefore bounds a time interval for the objects' last change. If you supply only LastChangedAfter, there is no upper boundary on the date. Parameter value is a DateTime object that specifies the date and time you want. false false
LastChangedBefore Specify the upper boundary of the object modification date and time by which to filter objects found. The cmdlet returns only the objects that have last changed before the date and time specified. Supplying both LastChangedAfter and LastChangedBefore bounds a time interval for the objects' last change. If you supply only LastChangedBefore, there is no lower boundary on the date. Parameter value is a DateTime object that specifies the date and time you want. false false
LastChangedOn Specify the object modification date by which to filter objects found, searching for objects that have last changed within the date specified. This parameter is mutually exclusive with the LastChangedAfter and LastChangedBefore parameters. Parameter value is a DateTime object that specifies the date you want. false false
LdapFilter Specify the LDAP search filter that defines your search criteria. Note that the search filter string is case-sensitive.

The cmdlet disregards this parameter if an Identity value is supplied. If you want this parameter to have effect, do not supply any Identity value on the command line. Instead, supply a SearchRoot value.

If you supply the LdapFilter parameter along with attribute-specific parameters, then your search returns objects that meet the conditions defined by the LDAP filter and have the specified attributes set to the specified values.

false false
Name Specify the name of objects you want to find. false false
PageSize Set the maximum number of items in each page of the search results that will be returned by the cmdlet. After the directory server has found the number of objects that are specified by this parameter, it will stop searching and return the results to the cmdlet. When the cmdlet requests more data, the server will restart the search where it left off. You can use this setting to adjust the number of requests (network calls) to the directory server issued by the cmdlet during a search.

Normally, the default page size is 50. You can view or modify this default setting by using the Get-QADPSSnapinSettings or Set-QADPSSnapinSettings cmdlet, respectively.

false false
ProgressThreshold Use this parameter to specify a delay, in seconds, before the cmdlet displays a progress bar that depicts the status of the running command in case of a lengthy operation. If the running command finishes before the threshold time has elapsed, a progress bar does not appear. The default threshold time setting can be configured by using the Set-QADProgressPolicy cmdlet. false false
Proxy For parameter description, see help on the Connect-QADService cmdlet. false false
ReturnPropertyNamesOnly This parameter causes the cmdlet to list the names of the object attributes whose values the cmdlet retrieves from the directory and stores in the memory cache on the local computer. Thus, when used in conjunction with the IncludeAllProperties parameter, it lists the names of all attributes of the respective directory object (such as a User object). For examples of how to use this parameter, see help on the Get-QADUser or Get-QADObject cmdlet.

Note: Caching an attribute guarantees that the value of the attribute can be read by using properties of the output object returned by the cmdlet. If a particular attribute is not in the cache, the output object may not have a property that would provide access to the value of the attribute.

false false
SearchAttributes Specify an associative array that defines the object attributes and values you want. The cmdlet searches for objects that have the specified attributes set to the specified values. 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 search. A value may include an asterisk character - a wildcard representing any group of characters. For information about associative arrays, type the following command at the PowerShell command-prompt:

help about_associative_array

false false
SerializeValues This parameter causes the cmdlet to output an object whose properties store the attribute values of the respective directory object that are loaded to the local memory cache. The value returned by each property of the output object is represented as a string (serialized) so as to facilitate the export of the attribute values to a text file. Thus, when used in conjunction with the IncludeAllProperties parameter, it allows an entire object to be exported from the directory to a text file. For examples of how to use this parameter, see help on the Get-QADUser cmdlet. false false
Service For parameter description, see help on the Connect-QADService cmdlet. false false
ShowProgress Supply this parameter if you want the cmdlet to display a progress bar that depicts the status of the running command in case of a lengthy operation. If this parameter is omitted, whether the cmdlet displays a progress bar depends upon the ShowProgress setting configured by using the Set-QADProgressPolicy cmdlet. false false
SizeLimit Set the maximum number of items to be returned by the cmdlet. Normally, the default size limit is 1000. You can view or modify this default setting by using the Get-QADPSSnapinSettings or Set-QADPSSnapinSettings cmdlet, respectively. false false
Type Specify the type of objects you want to find. The cmdlet searches for objects that have one of the objectClass attribute values set to the Type parameter value. false false
UseDefaultExcludedProperties When set to 'true', this parameter causes the cmdlet not to load a certain pre-defined set of attributes from the directory to the local memory cache. 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. Normally, this parameter is used in conjunction with IncudeAllProperties to avoid retrieval of unnecessary data from the directory server, thereby increasing performance of the search operation performed by the cmdlet.

Note: If a cmdlet does not cache a particular attribute, then the output object returned by the cmdlet may not have a property that would provide access to the value of the attribute.

false false
UseDefaultExcludedPropertiesExcept This parameter is deprecated, and has no effect. false false
UseGlobalCatalog For parameter description, see help on the Connect-QADService cmdlet. false false
WildcardMode Specify either 'PowerShell' or 'LDAP' as the parameter value. Normally, if this parameter is not supplied, the cmdlet assumes that WildcardMode is set to 'LDAP'. You can view or modify this default setting by using the Get-QADPSSnapinSettings or Set-QADPSSnapinSettings cmdlet, respectively.

The 'PowerShell' value causes the cmdlet to use PowerShell wildcards and quoting rules. Wildcards are processed on the client side, which may result in slow search performance.

For information about PowerShell wildcards and quoting rules, type the following commands at the PowerShell command-prompt:

   help about_wildcard
   help about_quoting_rule

The 'LDAP' value causes the cmdlet to use LDAP wildcards (asterisks only) and LDAP quoting rules (backslash as the escape character). Wildcards are processed on the server side, which enables faster search results.

false false

Examples

EXAMPLE 1

get-QADManagedObject 'domainName\userName' -Type 'group'

Description


Retrieve the groups for which a given user is assigned as the manager.

EXAMPLE 2

get-QADManagedObject 'domainName\userName' -Type 'group' -Proxy -ConsiderSecondaryOwnership

Description


Retrieve the groups for which the specified user is assigned as the manager (primary owner) or as a secondary owner.

EXAMPLE 3

get-QADManagedObject 'domainName\userName' -Proxy -ConsiderInheritedOwnership

Description


Retrieve the objects for which the specified user meets any of the following requirements:

- The user is assigned as the manager of the object
- The user belongs to any group that is assigned as
  the manager of the object
Personal tools