Get-QARSWorkflowInstance
From PowerGUI Wiki
Retrieve workflow instance records from ActiveRoles Server. Each record contains information about a certain workflow, whether pending or completed, that was originated by a particular operation 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-QARSWorkflowInstance [-AttributesChanges <hashtable>] [-ChangedAttributes <string[]>] [-CompletedAfter <DateTimeParameter>] [-CompletedBefore <DateTimeParameter>] [-CompletedOn <DayParameter>] [-CompletedRecently <RelativeDateTimeParameter>] [-Connection <ArsConnection>] [-ConnectionAccount <string>] [-ConnectionPassword <SecureString>] [-CreatedAfter <DateTimeParameter>] [-CreatedBefore <DateTimeParameter>] [-CreatedOn <DayParameter>] [-CreatedRecently <RelativeDateTimeParameter>] [-Credential <PSCredential>] [-InstanceID <string[]>] [-Operation <OperationIdentityParameter[]>] [-OperationType <OperationType[]>] [-Proxy] [-Service <string>] [-SizeLimit <int>] [-TaskStatus <TaskStatus[]>] [-UseGlobalCatalog] [-Workflow <IdentityParameter[]>] [<CommonParameters>]
Detailed Description
Use this cmdlet to retrieve information about workflow instances. When an operation request starts a workflow in ActiveRoles Server, it creates a workflow instance based on the settings found in the workflow definition. Each workflow instance stores the data indicating the current state of a single workflow that is in progress (pending) or finished (completed). For more information, see "Workflows" in the ActiveRoles Server Administrator Guide.
The objects returned by this cmdlet represent workflow instance records that meet the search conditions specified, allowing you to access information about the corresponding workflow instances. You can analyze the returned object to discover what operation started the workflow, when the workflow was started, and whether the workflow is completed. You can also pass the returned object to the Get-QARSApprovalTask cmdlet through the WorkflowInstance parameter in order to get information about the approval tasks, if any, that were originated within the workflow.
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 |
|---|---|---|---|---|
| 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 workflow instances that were finished 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 workflow instances that were finished 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 | |
| CompletedOn | Retrieve records for the workflow instances that were finished 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 workflow instances that were finished 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 workflows that were finished 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 workflow instance records associated with 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 workflow instance records associated with 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 workflow instance records associated 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 workflow instance records associated with 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 workflow instances associated with 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 | |
| InstanceID | Retrieve workflow instance records by ID. Parameter value is an array of strings, with each string representing the ID of the workflow instance to retrieve. | false | false | |
| Operation | Retrieve workflow instance records that are associated with the operation requests specified. Parameter value is an object or a collection of objects returned by the Get-QARSOperation cmdlet, or a string array of operation IDs. You can use this parameter to get information about the workflow instances originated by a particular operation request 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 | |
| TaskStatus | Retrieve records for the workflow instances that have a certain status, such as finished (completed) or waiting for a certain activity to be completed (pending). Valid parameter values are:
Pending Completed Canceled | false | false | |
| UseGlobalCatalog | For parameter description, see help on the Connect-QADService cmdlet. | false | false | |
| Workflow | Retrieve workflow instance records that are based on the workflow definitions specified. Parameter value is an object or a collection of objects returned by the Get-QARSWorkflowDefinition cmdlet, or an array of strings each of which represents the Distinguished Name of a workflow definition object. You can use this parameter to get information about the instances of a particular workflow definition in ActiveRoles Server. | false | false |
Examples
EXAMPLE 1
Get-QARSWorkflowInstance -CreatedBefore ((get-date).AddDays(-30)) -TaskStatus Pending
Description
List the workflow instances that were created more than 30 days ago and have not been completed.
EXAMPLE 2
Get-QARSWorkflowInstance -Workflow 'CN=Approval by Primary Owner (Manager),CN=Builtin,CN=Workflow,CN=Policies,CN=Configuration' -TaskStatus Pending
Description
List all workflow instances that were created based on a particular workflow definition and have not been completed.
