Get-QARSApprovalTask
From PowerGUI Wiki
Retrieve approval task records from ActiveRoles Server. Each approval task record represents a task, whether pending or completed, to approve or reject a certain change request in ActiveRoles Server.
This cmdlet is part of the Quest ActiveRoles Server product. Use Get-QARSProductInfo to view information about ActiveRoles Server.
Contents |
Syntax
Get-QARSApprovalTask [-Approver <IdentityParameter[]>] [-ApproverIsMe] [-AttributesChanges <hashtable>] [-ChangedAttributes <string[]>] [-CompletedAfter <DateTimeParameter>] [-CompletedBefore <DateTimeParameter>] [-CompletedBy <IdentityParameter[]>] [-CompletedByMe] [-CompletedOn <DayParameter>] [-CompletedRecently <RelativeDateTimeParameter>] [-Connection <ArsConnection>] [-ConnectionAccount <string>] [-ConnectionPassword <SecureString>] [-CreatedAfter <DateTimeParameter>] [-CreatedBefore <DateTimeParameter>] [-CreatedOn <DayParameter>] [-CreatedRecently <RelativeDateTimeParameter>] [-Credential <PSCredential>] [-Operation <OperationIdentityParameter[]>] [-OperationType <OperationType[]>] [-Proxy] [-Service <string>] [-SizeLimit <int>] [-TaskID <string[]>] [-TaskStatus <TaskStatus[]>] [-UseGlobalCatalog] [-WorkflowInstance <WorkflowInstanceParameter[]>] [<CommonParameters>]
Detailed Description
Use this cmdlet to retrieve information about tasks of approving changes to directory data that were requested using ActiveRoles Server.
When changes are attempted that require approval, one or more approval task records are created in the ActiveRoles Server Management History data store, and associated with the operation record representing the change request.
Once all approval tasks associated with an operation are completed, the operation record is marked completed and the requested changes are either applied or denied depending the approvers' resolutions on the approval tasks (Approve or Reject). When any task associated with an operation receives the Reject resolution, the entire operation is denied and the requested changes are disregarded. When all tasks associated with the operation receive the Approve resolution, the operation is allowed and the requested changes are applied. For more information on the change approval function, see "Approval Workflow" in the ActiveRoles Server Administrator Guide.
The objects returned by this cmdlet represent approval task records that meet the search condition specified, allowing you to access information about the approval tasks and the operation they govern. You can discover who is expected to perform approval tasks, when and by whom the requested changes were approved or rejected, as well as get identities of approval task records for further processing in order to perform approval tasks.
The cmdlet has optional parameters that determine the server and the security context for the operation. The connection parameters could be omitted since a connection to a server is normally established prior to using this 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.
Note that this cmdlet requires a connection to the ActiveRoles Server Administration Service, so the Proxy parameter must be used to establish a connection.
Parameters
| Name | Description | Required? | Pipeline Input | Default Value |
|---|---|---|---|---|
| Approver | Retrieve records for the approval tasks that have the specified security principal (such as a user or group) designated as an approver (a person authorized to approve or reject the respective change request). Parameter value can be an array of strings, with each string representing the Distinguished Name (DN), Canonical Name, Domain\Name, User Principal Name, SID or GUID of a security principal object in Active Directory. You can use this parameter to retrieve information about approval tasks assigned to particular persons. | false | false | |
| ApproverIsMe | Retrieve records for the approval tasks that are assigned to the security principal (such as a user) in whose security context the cmdlet is currently running. | false | false | |
| AttributesChanges | Retrieve records relating to requests for changing the specified attributes to the specified values. You can use this parameter to limit your search based on particular changes requested or made to particular attributes. Parameter value is an associative array that specifies the attributes and values you want. Array syntax:
@{attr1='val1';attr2='val2';...} In this syntax, each of the key-value pairs is the LDAP display name of an attribute and the value set on the attribute in accord with the change request. Examples: @{description="Text"} Search for requests that change Description to the text specified. @{description="Text*"} Search for requests that change Description to any value that begins with the text specified. @{description="$null"} Search for requests that clear Description. When multiple attributes are specified, the search returns the records that involve changes to all those attributes (the search conditions are combined using a logical AND operator). For information about associative arrays, type the following command at the PowerShell command-prompt: help about_associative_array | false | false | |
| ChangedAttributes | Retrieve records relating to change requests targeted at the attribute specified. Parameter value can be an array of strings, with each string representing the LDAP display name of an attribute (such as 'description' or 'sAMAccountName'). You can use this parameter to limit your search based on any changes requested or made to particular attributes. When multiple attributes are specified, the search returns the records that involve changes to any of those attributes (the search conditions are combined using a logical OR operator). | false | false | |
| CompletedAfter | Retrieve records for the approval tasks that were completed (that is, received the Approve or Reject resolution) after the date specified. Parameter value can be a DateTime object or a string that specifies the date you want. Thus, you can supply "Today" as a parameter value. | false | false | |
| CompletedBefore | Retrieve records for the approval tasks that were completed (that is, received the Approve or Reject resolution) before the date specified. Parameter value can be a DateTime object or a string that specifies the date you want. Thus, you can supply "Today" as a parameter value. | false | false | |
| CompletedBy | Retrieve records for the approval tasks that were completed by the security principal (such as a user) specified. Parameter value can be an array of strings, with each string representing the Distinguished Name (DN), Canonical Name, Domain\Name, User Principal Name, SID or GUID of a security principal object in Active Directory. You can use this parameter to retrieve information about approval tasks to which a particular person has applied the Approve or Reject resolution. | false | false | |
| CompletedByMe | Retrieve records for the approval tasks that were completed by the security principal (such as a user) in whose security context the cmdlet is currently running. | false | false | |
| CompletedOn | Retrieve records for the approval tasks that were completed (that is, received the Approve or Reject resolution) within the date specified. Parameter value can be a DateTime object or a string that specifies the date you want. Thus, you can supply "Today" as a parameter value. | false | false | |
| CompletedRecently | Retrieve records for the approval tasks that were completed (that is, received the Approve or Reject resolution) during the recent time period specified. Parameter value is a TimeSpan object that specifies the time period you want. For example, if you supply a time span of 3 days, the cmdlet searches for the records regarding the approval tasks completed during the last 3 days. | 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 | |
| CreatedAfter | Retrieve approval task records for the change requests that occurred after the date specified. Parameter value can be a DateTime object or a string that specifies the date you want. Thus, you can supply "Today" as a parameter value. | false | false | |
| CreatedBefore | Retrieve approval task records for the change requests that occurred before the date specified. Parameter value can be a DateTime object or a string that specifies the date you want. Thus, you can supply "Today" as a parameter value. | false | false | |
| CreatedOn | Retrieve approval task records for the change requests that occurred within the date specified. Parameter value can be a DateTime object or a string that specifies the date you want. Thus, you can supply "Today" as a parameter value. | false | false | |
| CreatedRecently | Retrieve approval task records for the change requests that occurred during the recent time period specified. Parameter value is a TimeSpan object that specifies the time period you want. For example, if you supply a time span of 3 days, the cmdlet searches for the task records specific to the change requests that occurred during the last 3 days. | false | false | |
| Credential | For parameter description, see help on the Connect-QADService cmdlet. | false | false | |
| Operation | Retrieve approval task records that are associated with the operation records specified. Parameter value is an object or a collection of objects returned by the Get-QARSOperation cmdlet, or an array of operation string IDs. You can use this parameter to access information about approval tasks specific to a particular change request that requires approval in ActiveRoles Server. | false | false | |
| OperationType | Retrieve records for the change requests of the category specified. Valid parameter values are:
Create Delete Copy Modify GroupMembershipChange Move Rename Deprovision UndoDeprovision Parameter value can be any combination of the listed values, separated by commas. For example, 'Create,Modify' limits the search to the requests for changing attributes of existing objects or creation of new objects. If this parameter is omitted, records are retrieved regardless of the change request category. | false | false | |
| Proxy | 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 | |
| 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- or Set-QADPSSnapinSettings cmdlet, respectively. | false | false | |
| TaskID | Retrieve approval task records by ID. Parameter value is an array of strings, with each string representing the ID of the task to retrieve (you can view task ID in the Approval section of the ActiveRoles Server Web Interface). | false | false | |
| TaskStatus | Retrieve records for the approval tasks that are completed with a certain resolution (Approve or Reject) or pending (awaiting resolution). Valid parameter values are:
Pending Canceled CompletedApproved CompletedRejected Parameter value can be any combination of the listed values, separated by commas. For example, 'CompletedApproved,CompletedRejected' limits the search to the tasks that have been completed with any resolution. If this parameter is omitted, records are retrieved regardless of the tasks status (a search is performed against all tasks). | false | false | |
| UseGlobalCatalog | For parameter description, see help on the Connect-QADService cmdlet. | false | false | |
| WorkflowInstance | Retrieve approval task records that are associated with the workflow instance records specified. By using this parameter, you can get information about the approval tasks originated by a particular workflow instance. Parameter value is an object or a collection of objects returned by the Get-QARSWorkflowInstance cmdlet, or an array of workflow instance string IDs. | false | false |
Examples
EXAMPLE 1
Get-QARSApprovalTask -Approver 'MyDomain\JSmith'
Description
List all approval tasks awaiting response from the user 'MyDomain\JSmith'.
EXAMPLE 2
Get-QARSApprovalTask -ApproverIsMe -TaskStatus Pending |
%{$_.Operation}
Description
List all change requests (operations) awaiting approval by the current user.
EXAMPLE 3
Get-QARSApprovalTask -Approver 'MyDomain\JSmith' -TaskStatus Pending |
%{$_.Operation}
Description
List all change requests (operations) awaiting approval by the user 'MyDomain\JSmith'.
EXAMPLE 4
Get-QARSApprovalTask -CompletedRecently ([TimeSpan]::FromDays(7)) -CompletedBy 'MyDomain\JSmith' -TaskStatus CompletedApproved |
%{$_.Operation}
Description
List all change requests (operations) that were approved by the user 'MyDomain\JSmith' during last week.
EXAMPLE 5
Get-QARSApprovalTask -CompletedRecently ([TimeSpan]::FromDays(7)) -CompletedBy 'MyDomain\JSmith' -TaskStatus CompletedRejected
Description
List all approval tasks that the user 'MyDomain\JSmith' completed with the Reject resolution during last week.
