Workflows – Saving object properties
Workflows configured in the Active Roles Console support saving object properties when running the workflow with the Saving Object Properties activity. The properties are saved in the workflow data context and can be retrieved by other workflow activities either before or after the object changed.
Saving object properties is useful for situations that require knowing not only the current state or properties of the changed object, but also its previous states or property values. Such earlier states or property values may be required for informational, archival or decision making purposes.
For example, to notify users and administrators of object deletions, you can create a workflow that:
-
Starts when requesting the deletion of the object.
-
Saves the name of the object to be deleted.
-
After the object is deleted, it sends a notification message with the saved name of the deleted object.
Workflow configuration options
The Saving Object Properties activity has the following configuration options:
-
Activity target: Specifies the object whose properties will be saved. The available settings are the following:
-
Workflow target object: Specifies the target object of the request in a change workflow that started the workflow.
For example, in case of a change workflow starting with the delete request of an object, selecting this setting will result in the activity saving the properties of the object to be deleted.
-
Fixed object in directory: Specifies a particular object that you select in Active Directory.
-
Object identified by workflow parameter: Specifies the object via the value of a certain parameter in the workflow. You can select the parameter from the workflow definition.
-
Object from workflow data context: When selected, the activity will select the object based on the workflow environment data collected while running the workflow. You can select the object for the activity when the workflow is initiated.
-
Object identified by DN-value rule expression: Specifies the object via its Distinguished Name (DN) by the string value of a certain rule expression. By using a rule expression, you can compose a string value based on the properties of various objects found in the workflow environment when running the workflow. You can create the desired rule expression when you configure the activity.
-
Target properties: Specifies the object properties you want the activity to save. The Workflow Designer contains a default list of properties; however, you can change the list as you need.
By default, the activity saves all single-value non-constructed attributes found in the directory schema of the target object, including custom virtual attributes added to the directory schema by Active Roles.
-
Notification: Configures notifications for the runs of the activity, and subscribes recipients to the following notification events:
-
Activity completed successfully: Sends a notification email if no significant errors occurred during the run of the activity.
-
Activity encountered an error: Sends a notification email if significant errors occurred during the run of the activity.
The notification settings specify the notification events and recipients. When run by the workflow, the activity prepares a notification message according to the specified event. Active Roles retains the message prepared by the activity, and sends the message to the specified recipients when the event occurs.
-
Error handling: Specifies the action to take when detecting any errors. Selecting Continue workflow even if this activity encounters an error will suppress any errors detected by Active Roles during the workflow run. Leaving this setting clear will result in Active Roles stopping the workflow if the activity detects any errors. By default, this setting is not selected.
Retrieving saved properties
If you use any workflows that include the Save Object Properties activity, you can configure additional activities to retrieve the object property information saved by the Save Object Properties activity. You can do this by three means:
-
Using a Script activity with the following expression:
$workflow.SavedObjectProperties("activityName").get("attributeName")
In this expression, activityName is the name of the Save Object Properties activity, while attributeName is the LDAP display name of the attribute representing the property you want the script to retrieve.
NOTE: You must specify an attribute listed in the Target properties setting of the Save Object Properties activity. Otherwise, the expression will return no property value during runtime.
-
Adding the Workflow - Saved Object Properties token to the notification message template. To do so:
-
In the Insert Token dialog, in the list of tokens, click Workflow - Saved Object Properties, then click OK.
-
In the dialog that appears, select the name of the Save Object Properties activity and the saved property you want the token to retrieve.
NOTE: You must specify an attribute listed in the Target properties setting of the Save Object Properties activity. Otherwise, the token you configured will return no property value during runtime.
-
If you use an If-Else branch condition, a Search filter, or a Create, Update or Add Report Section activity, by selecting the Property of object from workflow data context configuration option. To do so:
-
In the Object Property dialog, click the link in the Target object field, then click More choices.
-
In the dialog that appears, click Saved Object Properties. Then, in the Activity list, select the name of the Save Object Properties activity and click OK.
-
In the Object Property dialog, click the link in the Target property field, then select the property you want.
NOTE: You must specify an attribute listed in the Target properties setting of the Save Object Properties activity. Otherwise, the entry you configured will return no property value during runtime.
Getting started
For more information on how to configure object property saving in a workflow, see Configuring a Save Object Properties activity in the Active Roles Administration Guide.
Workflows – Modifying requested changes
Change workflows configured in the Active Roles Console support updating change requests that started a workflow with the Modify Requested Changes activity. This activity lets you add or remove changes to the properties of the workflow target object while the workflow is running.
For example:
-
In a workflow that starts when requesting the creation of an object, you can use the Modify Requested Changes activity to either modify the properties that will be assigned to the new object, or change the container in which the object will be created.
-
In a workflow that starts when requesting the change an object, you can use the Modify Requested Changes activity to modify the requested property changes of the object.
NOTE: The Modify Requested Changes activity is not available in automation workflows.
Workflow configuration options
The Modify Requested Changes activity has the following configuration options:
-
Target changes: Specifies the property changes to add or remove from the change request. Use this setting to select:
-
The Property (or properties) you want the activity to change.
-
The Action to perform for each property (for example, adding, setting or removing the value of the property, or removing the property itself from the request).
-
The Value to add, remove or modify.
You can add, remove and modify values both for single-value and multi-value properties, with the following options.
NOTE: The various properties may only support some of the following settings.
-
Fixed object in directory: Specifies a particular object that you select in Active Directory.
-
Text string: Lets you specify the value of the property manually via a string.
-
Workflow target object: Specifies the target object of the request in a change workflow that started the workflow.
-
Property of workflow target object: Uses the value of a specific property of the target object in the request that started the workflow. When selecting this option, you can select the property from a list of object properties.
-
Workflow initiator object: Uses the object that initiated the workflow. When selecting this option, you can select the object from a list.
-
Property of workflow initiator: Uses the value of a specific property of the user who initiated the workflow. When selecting this option, you can select the property from a list of object properties.
-
Object identified by workflow parameter: Specifies the object via the value of a certain parameter in the workflow. You can select the parameter from the workflow definition.
-
Object from workflow data context: When selected, the activity will select the object based on the workflow environment data collected while running the workflow. You can select the object for the activity when the workflow is initiated.
-
Object identified by DN-value rule expression: Specifies the object via its Distinguished Name (DN) by the string value of a certain rule expression. By using a rule expression, you can compose a string value based on the properties of various objects found in the workflow environment when running the workflow. You can create the desired rule expression when you configure the activity.
-
Changed value of workflow target object property: Uses the value that the workflow requests to be assigned to a certain property of the workflow target object. When selecting this option, you can select the property from a list of object properties.
-
Workflow parameter value: Uses the value of a certain parameter of the workflow. When selecting this option, you can select the property from a list of workflow parameters.
-
Property of object from workflow data context: Uses the value of a certain object property selected by the activity on the basis of the data found in the workflow run-time environment. You can choose the desired property and specify which object you want the activity to select when the workflow runs.
-
Value generated by rule expression: Uses the string value of a certain rule expression. By using a rule expression you can compose a string value based on properties of various objects found in the workflow runtime environment. You can create the desired rule expression when you configure the activity.
-
Notification: Configures notifications for the runs of the activity, and subscribes recipients to the following notification events:
-
Activity completed successfully: Sends a notification email if no significant errors occurred during the run of the activity.
-
Activity encountered an error: Sends a notification email if significant errors occurred during the run of the activity.
The notification settings specify the notification events and recipients. When run by the workflow, the activity prepares a notification message according to the specified event. Active Roles retains the message prepared by the activity, and sends the message to the specified recipients when the event occurs.
-
Error handling: Specifies the action to take when detecting any errors. Selecting Continue workflow even if this activity encounters an error will suppress any errors detected by Active Roles during the workflow run. Leaving this setting clear will result in Active Roles stopping the workflow if the activity detects any errors. By default, this setting is not selected.
-
Additional settings: The Modify Requested Changes activity also contains the following settings:
-
Modify object creation requests so as to create objects in this container: Allows you to change the container where Active Roles creates the new objects, while ensuring that the policies and workflows will be applied from the container where the object will be created (rather than from the container that was originally specified in the object creation request).
-
Include or exclude these controls from the change request: Allows you to add or remove Active Roles controls from the request. "Controls" are pieces of data that provide additional information for Active Roles on how to process the request.
If you do not specify any controls in the request, Active Roles will process the request based on the type of the request only. You can either configure the activity to add certain controls to the request (include controls) or to ensure that certain controls never occur in the request (exclude controls). For more information about adding Active Roles controls to a request, see the Active Roles SDK documentation.
Getting started
For more information on how to configure object property saving in a workflow, see Configuring a Modify Requested Changes activity in the Active Roles Administration Guide.
Workflows – Initialization scripts
When running a workflow instance, Active Roles uses a single PowerShell operating environment (called "runspace") for all script activities held in that workflow. The workflow runtime engine creates a runspace once the workflow instance started, and maintains the runspace during the run of the workflow instance.
When you configure a workflow, you can specify PowerShell commands you want the workflow runtime engine to initialize immediately after creating the runspace. These commands are part of an initialization script that the workflow engine runs prior to performing the script activities.
With an initialization script, you can define runspace configuration data separately from the logic of other script activities, and you can use it to initialize the environment for initializing script activities. Specifically, you can:
-
Load PowerShell modules and snap-ins. All activity scripts can use the modules and snap-ins loaded in the initialization script without having to load the prerequisite modules or snap-ins on a per-activity basis.
The modules and snap-ins loaded in the initialization script are available to all script activities at workflow runtime. For example, the Import-Module 'SmbShare' command added to the initialization script makes the Server Message Block (SMB) Share-specific cmdlets available to all script activities within the workflow.
-
Initialize environment-specific variables, referred to as "global variables". All activity scripts can retrieve and update global variables, which makes it possible to exchange data between different activity scripts.
The global variables are visible to all script activities at workflow runtime. For example, the $rGuid = [Guid]::NewGuid() command added to the initialization script makes the $rGuid variable available to all script activities within the workflow. To reference a variable defined in the initialization script, the activity script must use the $global: qualifier, such as $global:rGuid.
TIP: If the run of the workflow instance is suspended (for example, because it is waiting for approval), then resumed (for example, after receiving approval), the runspace is reinitialized, so the global variables may change.
In such cases, if you need to preserve the value of a global variable, add the [Persist()] attribute to the variable name in the initialization script, such as [Persist()]$rGuid = [Guid]::NewGuid(). Global variables defined this way are saved to a persistent storage when the workflow instane is suspended, then restored from the storage when the workflow instance is resumed.
To save a variable, Active Roles creates and stores an XML-based representation of the object represented by the variable, similarly to the Export-Clixml command in Windows PowerShell. When restoring the variable, Active Roles retrieves the XML data that represents the object, and creates the object based on that data, similarly to the Import-Clixml command.
Getting started
You can create new initialization scripts in the Workflow Designer of the Active Roles Console.
To start creating a new initialization script
-
In the Active Roles Console, navigate to Configuration > Policies > Workflow.
-
To open the Workflow Designer, select the workflow you want to configure.
-
In the details pane, click Workflow options and start conditions > Configure.
-
To open the initialization script editor, click Initialization script.
The Initialization script tab then displays the currently used script (if it exists). To add a new script or modify the existing one, use the editor.
Workflows – Searching for expiring users
You can use the Search activity in an Active Roles workflow to search directory objects (such as users or groups), that match the criteria you specify with your search terms. Active Roles can then pass the search results to other workflow activities to perform additional actions.
The Search activity also supports searching for user accounts that will expire within the specified amount of time.
Getting started
To search for user accounts that expire within a certain amount of days, use the Search activity of the Workflow Designer in the Active Roles Console.
To search for expiring user accounts with a workflow
-
In the Active Roles Console, navigate to Configuration > Policies > Workflow.
-
To open the Workflow Designer, select the workflow you want to configure.
-
Add a Search activity to the workflow, or right-click an existing one, and select Properties.
-
To filter the search to user accounts that will expire, select Retrieve only expiring user accounts.
-
In the dialog that opens, specify the number of days to check. The Search activity will list user accounts that expire within the specified number of days.
