User Activity

The user Activity is used to create an actionable item assigned to a user. In addition the User Activity creates a Task that is assigned to one or more users. The Task governs the actions the user must complete and when. The User Activity configures how the Task will be assigned and completed, while the Task is the object that governs how the user interacts with the system while the Task is running.

Because User Activities always assign a Task to a user, the terms 'User Activity' and 'Task' are often used interchangeably. Technically, the Task is a separate object from the User Activity in the Process Director system, but both are inextricably linked, and are initiated, run, and completed in tandem. From the end user's perspective, the User Activity and Task are essentially indistinguishable; however, from an implementer's perspective these objects are not the same. When creating a condition, the dropdown menu for the Choose System Variable dialog box has separate groups for Tasks and Timeline activities, each with their own attributes to access.

The Task options are only relevant to a user Task, while the Timeline Activity options are applicable to all Process Timeline activity types. The Task—which, again, is an inextricable part of a User Activity—has some evaluable properties that are not relevant to other types of Timeline Activity and are only useable when a user Task is running.

The distinction between the two is not enormously important, but it's something to keep in mind as an implementer, especially when building conditions related to User Activities. Some of the conditions you might wish to evaluate can only be found in the Task group of the dropdown menu. Similarly, the Task group is not relevant for creating conditions for non-User activities.

User Assignment #

When a User activity starts, task assignment to the configured participants runs immediately, and only runs once. If there are any running or completed instances of the Process Timeline, changing the Timeline definition will not affect them. Once the Task assignment has been made for an activity, the only way to change it in a running activity instance is to open the Process Timeline instance, open the properties for the running activity, and manually change participants or, if the configured participants have been changed, restart the activity. Both of these actions are an administrative intervention in the running instance.

The important thing to remember is that Task assignment can only occur once, and only when the activity starts running. Only the participants who are configured when the activity starts will be included in the task assignment.

You should also note that the Restart Users property, described below in the Advanced Options Tab section, may still restart some previously assigned users, based on the settings chosen. This property should be set to Start only configured task participants to ensure that only the currently configured users are assigned to the task upon restart.

If a Task has been assigned to a user, it will appear in the user's Task List. The user must complete the task before it can be removed from the Task List. A user who is assigned a task will be automatically given permission to any object in the Process Timeline package so they may complete the task. Examples of this task can be an approval task or update task.

When a Task is assigned to a user with an invalid UID or user ID, Process Director will immediately stop the process, and place the Process Timeline Activity into an error state. This is also true for anonymous user assignments if the email address isn't a valid format (Process Director can't validate the email address itself, only the format).

Note If your process includes tasks for unauthenticated users, please refer to the documentation on Anonymous Users for special concerns that may apply to some settings.

In addition to the common properties tabs that appear for all Timeline activities, the configuration settings below are unique to this Activity Type.

Documentation Example #

The example below walks through the process of configuring a User Activity.

Configure a User Activity

Participants Tab #

Determines which users are a participants of the user task. Users can be added via the Add Participant button, and the participants can be specified via the Participant Type dropdown.

By default, this property is set to choose the Timeline Initiator, which is the user who prompted the Process Timeline to begin. There are several other options available to choose:

  • The Groups participant type will select all members of a Process Director User Group for Task assignment. BP Logix recommends that the Group participant type be selected whenever possible.
  • The Business Rule participant type will assign Users that are returned by a Business Rule. Unlike Groups, Business Rules reside in the Content List, and can be edited by anyone with access to them. So, while not as secure as Groups, assignment by Business Rule is more flexible, and enables complex assignment scenarios.
  • The System Variable participant type uses a System Variable that returns a User or Group to assign a Task.
  • The From Form Field participant type enables you to specify the task assignee from a User Picker Form field.
  • The Users participant type enables you to select specific users as Task assignees. This participant type is not recommended for activities that have multiple assignees, or where a single user might participate in many processes.

For more complex user assignment scenarios, the Add Participant button enables you to add as many participants as you need to an activity. It also enables you to choose different participant types for each assignee. As a practical matter, there is no upper limit to the number of Users assigned a Task, though, in most cases, the number of people assigned to a Task is relatively small.

When multiple users are assigned to a task, a Subtask can be created for each user. You must have a form field that specifies the name of each desired subtask.

In this example, each user is assigned a Subtask Name from a different form field, i.e., Subtask1Name, Subtask2Name, and Subtask3Name. When the users are assigned their task, Both the Task Name (which is the Activity's Name) and Sub Task Name will be assigned to them, so that you can track both the task and subtask for each user as they are completed.

For Process Director v 6.0.100 and higher, each subtask can have a unique due date, assigned via a System Variable. Unlike prior versions, where a single due date was assigned to both the Timeline Activity and all of it's included subtasks, you can now configure a Business Rule to return a unique Due Date for each subtask, based on any evaluable condition, such as the Sub Task Name.

In this example, the Business Rule, named SubtaskDueDatesBR, will return one of three different due dates, based on the name of the Subtask, e.g. "Subtask1", "Subtask2", or "Subtask3". On the Due Date tab of the Timeline Activity, this Business Rule is reverenced in the Set due date from system Variable property to provide the appropriate due dates for each subtask.

Since each subtask is assigned to as different user, Process Director will pass the Sub Task Name for that user to the Business Rule when the subtask is assigned, which will return the unique due date for each subtask participant.

Results Tab #

The Results Tab appears when either the User or Wait Activity Types are selected. The Process Activity also has a result, which is generated automatically, and is explained in the "Results of a Process Activity" section below.

A user Activity in the Process Timeline can have results assigned to it. Multiple results can be added to an Activity by clicking on the Add Result button.  Each result will have its own properties, which are presented in a tabbed interface.

The results will be used as the Activity result for the task, which will appear in the Routing Slip and in the Timeline Administration screen.

The name of the result, which will appear on all Forms, and as the completed result in the Timeline instance, if the result is selected by a user.

A brief text description of the result.

Result handling is the methodology used to respond to one or more Activity Results. We may need to do different things when different results are selected. Result handling defines how our application will respond to this selection. By default, when a user selects a result button, the activity completes, the result is recorded, and Process Director moves on to the next activity.

Let's take an example of an approval activity that has three configured results, and look at what result handling might be needed for each result:

  • Approve: No handling needed. Move to the next eligible activity.
  • Resubmit: Send back to the submitter for changes.
  • Deny: End the Process Timeline.

For each result, we need the application to do something completely different, but we need to implement result handling for the Resubmit and Deny results.

For most use cases, BP Logix recommends that approval activities all be placed inside a Parent activity with appropriate Looping conditions. Encapsulating the approval activities inside a Loop offers the easiest and most efficient method for configuring approval activities and handling disparate results.

Conditions Tab #

This is one of the two tabs displayed for each result's configuration settings.

The Conditions Tab includes the following controls.

Conditions Tab

If the specified percentage of users select this result, the task will be considered complete, with this result recorded as the Activity result. For example, if you wish the task to be concluded when 75% of users select this result, then the value you'd place in the text box would be "75".

If the specified number of users select this result, the task will be considered complete, with this result recorded as the Activity result. For example, if you wish the task to be concluded when 3 users select this result, then the value you'd place in the text box would be "3".

If a user selects this result, the specified confirmation prompt will be displayed to the user, requiring the user confirm this selection before it is recorded.

This enables you to select a condition, or conditions, which, when met, will complete this task with the result recorded as the Activity result.

Important When setting an Activity result condition, you must set the Completed When dropdown to "When Any Result Condition Is Met" to complete the Activity on the Completed When tab of the Activity definition.

This enables you to select a condition, or conditions, which, when met, will display this result option to the user. If the condition(s) aren't met, the result button won't be displayed to users.

This is a check box that, when checked, designates the result as the default result for the Timeline Activity. When setting a Completed When condition, you must specify a default result, or the Activity will either not end as expected, or will go into an error state.

Conditional Termination

Conditional termination is the methodology for ending an activity when specific conditions apply. There are three primary methods for applying conditional termination.

Consensus Results

Consensus results are only applicable to Timeline Activities that have more than one user assigned. On the Results tab of a user activity, each Result has two properties that enable you to specify that the activity will end when either a percentage or number of users select a specific result: %/# of participants that choose this result.

When a Task is assigned to multiple users, you can use one of these properties to specify that this result will be selected if the configured percentage or number of participants, respectively, chooses that result.

For example, if we have an activity that has 5 users as participants, we can set the # of participants that choose this result property to '3'. If we do, then when the activity runs, if three of the participants choose this result, the activity will complete, and the result will be recorded as the activity result. If the other two participants haven't yet completed the task, they'll be marked as not needed.

So, if we had two results, Approve and Deny, we might implement a more sophisticated set of conditions. We could set Approve as the result if three participants select it but set Deny as the result if only one participant selects it.

Obviously, setting this property requires some thought. If you have four results, and five participants are assigned the task when the activity runs, none of the results might have three of the participants select it. In that case, the activity will still end, but the result will be a list of all results selected by the participants.

When implementing consensus results, it's best to ensure that, irrespective of the results chosen by the participants, a definitive result is recorded for the activity.

Conditional Results

The Activity result condition met when property enables you to specify a condition that, when met, will set the configured result as the result for the activity.

Once the specified condition is met, the activity result is set, irrespective of the Task completion status of any participants. It's important to remember, however, that setting this property does not end the activity when the result is set. All participants in the Task will still be active, and, unless you end the activity, they can still participate and change the activity result. Your result will still be recorded when the condition is met, but activity participants can select their own results, which might be different.

For activities with a single user as a participant, an activity ends and the result is set at the same time the user selects a result button. But that's not true for activities with multiple participants. Each participant may select a different result, but the activity does not end until all participants have completed their Tasks. Similarly, setting a conditional result simply adds an additional result to the activity without completing it. By default, the activity won't complete until the user Tasks have been completed, so some additional configuration is required.

To complete the activity when a conditional result is set, you must also go to the Completed When tab and set the Completed When dropdown to When any Result Condition is Met. With this property configured, the activity will end when the conditional result is set. All active participants will be marked as Not Needed, and their tasks will be completed automatically.

Completed When Conditions

You can set a condition on the Completed When tab to complete an activity when a specified condition set evaluates as true. This condition is set using the When conditions met property. Once a condition has been specified, you'll need to set the set the Completed When dropdown to All Users Complete or Result Condition Met, to ensure the activity ends when the Completed When condition is true. Once again, some additional configuration is needed to supply a result when this configuration is implemented.

While setting a result does not end an activity automatically, an activity cannot end until a result has been set. If you set a Completed When condition to end an activity, then you must also configure a default result for the activity. Each result configured on the Results tab has a Default Result property. You must set one, and only one, result as the Default Result for the activity. Process Director must be able to identify a single result as the default to apply to the activity, or the activity cannot be completed. If you implement a Completed When condition without setting a Default Result, or if you select more than one result as the Default Result, then the activity will fall into an error state when the Completed When condition runs.

To resolve this error state administratively, you must open the Process Timeline definition to provide the proper Default Result configuration. You can then open the properties for the Timeline instance that's in the error state and navigate to its Administration/Timeline tab. You'll need to restart the activity that's in an error state, then click the Refresh button to prompt a reevaluation of the condition, which should set the appropriate Default Result and end the activity.

While the activity is in an error state, remember that the activity is still running, and the task assignments for the activity are still active. The error state only prevents the activity from completing. It does not prevent any action from the activity participants. A participating user can still complete their task by selecting a result, which would complete the activity. Of course, the result the user selects may not be the result you that desire as the Default Result. Only administrative action can ensure the correct configuration and clear the error state.

Options Tab

This is one of the two tabs displayed for each results configuration settings. The Options Tab includes the following controls.

Options Tab

This is a numeric value that determines the order in which the Activity result button will appear on a Form. You may order the Activity results in any order you desire. If you don't order the buttons manually, they'll be displayed in the order in which the result was created. In older versions of Process Director, Process Timeline Activity results were specified using a comma-separated list. The display of the buttons on the form for each result followed the order in which they were listed. Now, when migrating from an older release to this one, the display order of the results will be automatically preserved. To modify the order, adjust the "Button Order on Form" property of each result in the Activity Results tab.

It's a best practice to have a specific button order that you always use. For instance, at BP Logix, we always want our most positive result to appear first and the most negative result to appear last. Having a consistent button order across all of your forms provides a consistent user interface for your users.

Clicking on the icon allows you to select a custom icon from a list. The selected icon will appear on the Activity result's button on the Form.

The setting enables you to select a background color for the result button that will appear on the form.

The setting enables you to select a text color for the result button that will appear on the form.

This text box will accept a comma-separated list of string values. For tasks that can be completed by email, a user can complete the task by replying to the task assignment email with one of the strings in the list you enter into this control. For example, the result displayed above is the "Reject" result. You might put the following list of responses into this control: "Reject, No, Disapprove, Rejected, Not Approved". If a user replies to the task assignment email with "No"—or any of the other possible responses in the list—as the body of the email message, the Reject result will be recorded as the Activity result.

If this option is selected, then, if the user selects this result, then the Results Comments control in the Form can't be empty.

If this option is selected, then users can complete this task from their Task List without opening the Form for the process.

Important This feature requires the use of a custom Task List that includes a column to display the results.

When the user completes a task from the Task List, Process Director will display a small popup that indicates the task completion is in progress. Additionally, if the result selected is configured to require completion comments, Process Director will prompt the user for the comments before completing that task.

The size of the prompt and confirmation dialogs won't usually need to be changed, however, if, for some reason the size does need to be changed, there are custom variables available to change the width and height of the dialogs: nTaskCompleteDialogWidth, nTaskCompleteDialogHeight, nTaskCompletePromptDialogWidth, and nTaskCompletePromptDialogHeight. Documentation for these four custom variables can be found in the Miscellaneous Custom Variables topic of the Developer's Guide.

Check this box to specify that a given Activity result will cause validation to be skipped. The feature is especially useful for steps/activities that include an option for the user to abandon or reject a form, which the user should be able to accomplish without, for example, filling in all required fields.

Due Date Tab #

The standard options for the Due Date tab are described in the Due Date Tab section of the Timeline Activities topic. The User Activity Type also has an additional option specific to the User Activity Type.

A dropdown that specifies the actions to take when the Due Date expires. The following options are available.

Option

Result

Take no action

Lets the Activity continue running.

Cancel This Activity

Cancel the Activity and automatically advance to the next Activity in the Process Timeline.

Add These Users from Business Rule

Add users identified in the Business Rule.

Replace existing users with those in Rule

Add the user from the Business Rule and cancel any running users.

Cancel the entire Timeline

Cancel the Process Timeline.

Advanced Options Tab #

This tab provides many additional settings for controlling task assignment, completion, Activity restarts, and more, as described below.

Checking this option won't allow a parent Activity to complete until this Activity is complete. This is the default option. This usually applies to an Activity that is organized under a Parent Activity Type. If this Activity doesn't complete, then the Parent Activity can't complete.

By default, the Result of a user Activity that is completed by multiple users will be the single result selected by most users. For instance, if two users pick Reject and one picks Accept, the Activity result is set to "Reject". In the case of a tie, e.g., if one user selects Accept and one Reject, the Result is set to "Accept, Reject". Selecting this option on a user Activity causes the Result to be set to the comma-separated union of all Results selected by users. So, in the first example above, the Result would be set to "Reject, Reject, Accept" or some similar result. The order of the results in the results list isn't guaranteed.

Forces users to re-authenticate prior to completing a task. For example, when this option is selected, built-in users will be presented with a login screen, requiring them to log in prior to completing the task, even if they are currently logged in to Process Director. This is an extra security precaution.

Checking this option will cause a prompt to appear to users to enter signature comments when completing the task.

Checking this option will enable task sharing through the Shared Delegation feature. If this option isn't checked, this task won't be available for Shared Delegation.

Checking this option will enable users to complete the task by replying to an email without opening the Form associated with the Activity or Process Timeline. Process Director can monitor an email inbox, import and parse the emails, and search for specific text in the email to determine the result. If a possible result for an Activity is "Approved", a user can reply with the word "Approved" in the body text of the reply, and Process Director will complete the Activity with the result of "Approve".

Checking this option will enable users to invite others to perform the user task by forwarding the task assignment email to them. The task assignee can forward the email to a desired alternate, for example, and when that alternate clicks on a completion link in the email, the task will be completed with the appropriate result, and with an annotation that the task was completed by the users invited by the original task assignee.

If this option is checked, at least one user will be required to complete the task, or the task can't complete. Depending on how the task assignment is configured, it's possible that no users will be assigned to the task in certain scenarios. For instance, if a task restarts after all users have completed their assignment, and the assignment is set to "Start users that did not complete previously" there will be no available user to which the task can be re-assigned. Checking this option will assign the task to one of the previously completed users.

For Process Director v6.1.500 and higher, this property and the next property, Mark as not needed if no users assigned, are mutually exclusive. Checking this property will automatically disable the other property.

Important If an administrator cancels a user in an Activity where this option is set, the Activity will go into an error state. The administrator will have to cancel the Activity to cause it to move on.

For Process Director v6.1.500 and higher, this property, when checked, will immediately complete a Timeline activity as Not Needed when no particpants have been assigned to the activity.

This property and the previous property, Require at least one user to be assigned and complete this task, are mutually exclusive. Checking this property will automatically disable the other property.

Checking this option will, when the task is assigned to multiple users, allow the first user to accept the task to be assigned to complete the task. When the task begins, all of the configured users will receive a Task List item that requests them to accept the task. When opening the Form, an Accept Task button will be displayed at the bottom of the Form. When any of the configured users clicks the Accept Task button, Process Director will remove task acceptance request from the Task List of all the other configured users, and the task will be assigned solely to the user who accepted the task.

Checking this option will enable anonymous users to complete a task based on the user's email address. This is a required option when using the Email Anonymous Task List system variable. In the vast majority of use cases, however, the email address will be taken from a Form field identified on the Participants tab.

Note Access to Process Director for unauthenticated or anonymous users is enabled for Cloud and Subscription licenses. On-premise licenses using the legacy Tiered licensing model require an additional, optionally licensed component.

If this task is part of a Case Management application, checking the property will automatically display the Case Folder view when the user opens the task.

For Process Director v6.1.300 and higher, customers who use the Mobile Application component can, by checking this option, export user tasks to the Mobile Application for completion. Similarly, the most recent version of the Mobile Form Import Custom Task will automatically import user tasks and their status from the Mobile Application when invoked.

This option enables you to select how you wish to assign a task when multiple users are associated with the same task. You have the following options:

OPTION

DESCRIPTION

All in parallel

All users will be assigned the task at the same time, and will complete their actions at the same time as the other users.

All in series

Each user will be assigned the task individually, and each user must complete the assigned action before the task is assigned to the next user. The process will continue until all users have completed their actions. This method is known as serial assignment.

One (Round Robin)

Only one user will be assigned the task each time an instance of the Timeline is run. Each time an instance is run, a different user will be assigned the task until all users have been assigned an instance of the process. This will divide the assignments equally among all assigned users.

One (fewest tasks in this process)

Only one user will be assigned the task each time an instance of the Timeline is run. Process Director will assign the task to the user who has the fewest number of active tasks pending in this process. This method assigns the task to the user who has the smallest workload in this process.

One (fewest tasks overall)

Only one user will be assigned the task each time an instance of the Timeline is run. Process Director will assign the task to the user who has the fewest number of active tasks in their Task List. This method assigns the task to the user who has the smallest overall workload.

When using serial assignment (All in Series), you may wish to control the order in which participants are assigned, which will affect the method you use when selecting task assignees. First, you can assign multiple users via a Business Rule, and the users will be assigned in the order, from top to bottom, in which they appear in the Business Rule's Values tab. This method is probably the best one to implement, when you need to control the order of Task assignment to users. Next, you could configure the Participants tab of the User Activity to include multiple users. Again, users will be assigned from top to bottom, in the order they appear on the Participants tab. Finally, you could also assign users via a Form field. For example, if your Form has an array of User Pickers, users would, again, be assigned in the order in which they appear, from top to bottom, in the array."

This option determines how a user's tasks are displayed when a user is assigned two sequential tasks in a process. The default in Process Director is to automatically show the user's next task if it is in the current process.

For example, if a user completes a task in a Form, and is also assigned the next task in the sequence, once the user clicks the OK or other task completion button on the Form, the Form won't close, but will simply redisplay itself to allow the user to complete the next task in the sequence. For various reasons, you may wish to override this behavior, in which case the Form will close once the first task has been completed, and the user will have to re-open the Form to complete the next task in the sequence.

You have the following options for configuring the behavior of Process Director:

OPTION

DESCRIPTION

Automatically show user's next task if it is in this process

This is the default behavior, and will automatically redisplay the Form once the user completes the first task in the sequence.

Automatically show user's next task if it is for this step in a different process

This selection will automatically show the user's next task if the user is assigned a task in another process. For instance, if the current task starts a subprocess, and the user is assigned a task in the subprocess, the subprocess task will automatically be displayed.

Do not show the user's next task

Once a user completes the task, the Form will close, and the user must reopen the Form from the Task List to begin performing the next task.

Automatically show user's next task if it is for any step for any related sub- process.

 This selection will automatically show the user's next task if the user is assigned a task in either the current process or related sub-process.

Once an activity starts, it can be restarted, either automatically, or via administrative action. Some scenarios that would result in an activity restarting might be:

  • The activity is part of a Parent activity that implements an iterating loop.
  • The activity must restart when a condition has been met.
  • An administrator manually restarts an activity.

There are several factors that might force us to consider carefully how we want Task assignments to work when an activity restarts, including: Some activities may run for weeks or months. If an activity restarts six months after it initially ran, some or all of the original users might not even be available for assignment. We might want to exclude users who previously performed the task. We might want to assign the task both to all users who performed the task previously, and also any new users who have been configured to participate since the activity previously ran.

This option determines how participants are assigned to the Activity when it must be restarted, which is particularly relevant when an implementer changes the participants assigned to an Activity in the Process Timeline definition. An existing instance may have been created when different participants were configured to participate in the task. This option enables you to determine how to handle user assignments when the configured users have changed.

It is also important to note that the term "restart" is used for both:

  • Cases in which a running task is restarted while the task is still running, and
  • Cases in which a task has already been completed, but must be re-run, as in an iterative process, or as a result of a change to some condition.

In either case, the Restart Users options you select will be applied.

The following options are available:

OPTION

DESCRIPTION

Start only configured task participants

This option will assign the task to the currently configured users, irrespective of which users may have been previously assigned to the Activity.

Start configured and users all previously run in this task.

By choosing this option, you ensure that both the currently configured users, as well as any users who were previously assigned the task, are assigned the task.

Start only users that previously completed this task

This option will assign the task only to users who completed the task when it was previously run for this instance. Those users will be re-assigned the task irrespective of whoever is currently configured for task assignment in the Process Timeline definition.

Start from last completed user

If multiple users are assigned to the Activity instance, this option will re-assign the Activity to the last user who completed it when it was initially run.

Start users that did not complete previously

If multiple users are assigned to the Activity instance, this option will assign the task to users who did not previously complete it. For instance, if the Activity uses a round-robin assignment, the Activity will be assigned to one of the users who were not assigned it on the initial run. 

This property enables us to specify a condition set that, when met, will automatically prompt a restart of the activity. For instance, you might need to restart the activity based on some change to external data, some change to data on the Form, or because a specified amount of time has passed since the activity started. Clicking the action link labeled, Click to create condition, invokes the Condition Builder.

Keep in mind that any condition you build will, when met, automatically restart the activity. It doesn't matter if the activity is currently running, and users haven't yet completed it. If the condition set is met, all currently running activity users will be marked as Not Needed, the currently running activity will be completed, and the activity will restart, using the Restart Users setting you've selected. You should only configure this property for the relatively rare scenarios where you want to prompt an automatic restart.

This will allow you to specify a Form to use in this Activity. This controls the form displayed when a user opens their Task List.

This property enables you to specify a system variable that can return users who will be given shared task permission for this specific Activity. This enables dynamic task sharing per each Timeline Activity, as opposed to the normal task sharing, which is set universally.

Other Activity Types

To view the documentation for other Activity Types, you can navigate to them using the Table of Contents displayed in the upper right corner of the page, or by using one of the links below.

Notify: This Activity Type sends email notifications to users who aren't participants in the process.

Process: This Activity Type invokes a different process that will run as a separate, synchronous subprocess.

Script: This Activity Type enables you to invoke a custom script.

Custom Task: This Activity Type invokes a Custom Task to run when the Activity starts.

Form Actions: This Activity Type enables you to manipulate the Form used for the process.

Branch: This Activity Type enables you to change the operation of the Process Timeline to invoke a specified Activity.

Parent: This Activity Type serves as a container for other activities and to create a looping segment in a Process Timeline.

End Process: This Activity Type enables you to conditionally end a process.

Wait: This Activity Type enables you to pause a Process Timeline.

Case: This Activity Type enables you to manipulate the Case instance that is associated with the Process Timeline.