Once you have configured the application/approval lifecycle for a workflow – how it moves through various states towards completion – it may be important to control who can see and interact with applications in those various states. This will usually involve building roles for various actors, and assigning those roles in the context of the workflow or a specific assignment.

Introduction to application capabilities

There are many capabilities in mod_approval, but they are variations on a similar pattern:

<action>_<state>_application_<actor>

Application actions are:

view_in_dashboard - View applications in the applications dashboard
create - Create a new application
view - View the application, along with approval state and activity timeline
edit - Edit the application using form views for this stage
edit_full - Edit the application using form views used in this or previous stages
edit_without_invalidating_approvals - Edit an application that has already been approved without restarting the approval process
approve - Approve or reject the application
attach_file_to - Attach files to the application
view_comment_on - View comments on the application view screen
post_comment_on - Post comments on the application view screen
withdraw - Withdraw (unsubmit) the application – this does not make it draft
backdate - Set date fields to dates in the past
delete - Delete the application

Application states are:

draft - Never-submitted application
(no state) - Not-draft (submitted at least once) application
pending - The acting user is an approver on the application's current approval level
unsubmitted - Non-draft application waiting to be submitted at a form stage
in_approvals - Submitted application waiting to be approved (or rejected)
first_approval_level - Submitted application waiting to be approved at the first approval level (has not already been approved by someone else)

Application actors are:

applicant - The subject of the application
owner - The person who created or controls the application
user - Person who has been assigned the capability in the applicant's user context (useful for Staff Manager capabilities)
any - Person who has been assigned the capability in the application's assignment context (or above)

For example, edit_in_approvals_application_owner gives the bearer the ability to edit applications they control that are awaiting approval.

Application capability list

This section lists all of the application-related capabilities implemented in Totara 17, by action.

The Default column indicates the default system role the capability is assigned to:

user: Authenticated user role.
staffmanager: Role assigned to job assignment managers / temporary managers in the user contexts of their team's users.
approver: The Workflow Approver role assigned to approvers in the assignment context where they are assigned as approvers.
manager: The Workflow Manager role that can be assigned in assignment, workflow, tenant, or system context.

Capabilities assigned to Workflow Manager are also assigned to the Site Manager and Tenant Domain Manager roles.

Create application

Users are only ever able to create applications where the applicant resolves to an assignment where the user has one of these capabilities.

Human-readable name	System name	Default	Notes
N/A	~~create_application_owner~~	-	Not implemented, there is no owner until the application is created.
Create applications where they are the applicant	create_application_applicant	user	Allows users to create applications for themselves.
Create user's applications	create_application_user	none	Allows users to create applications about another user, such as a team member.
Create applications	create_application_any	manager	Allows users to create applications about other users, generally.

View draft applications in the dashboard

Draft applications are those that have never been submitted, have never left the first stage.

Note that application owners always have the right to view draft applications, because they have created them. They can see the listing, even if they can't view the details.

Human-readable name	System name	Default	Notes
N/A	~~view_draft_in_dashboard_application_owner~~	-	Not implemented, owner can always view their own draft applications on the dashboard.
View draft applications in the dashboard where they are the applicant	view_draft_in_dashboard_application_applicant	none	-
View user's draft applications in the dashboard	view_draft_in_dashboard_application_user	none	-
View draft applications in the dashboard	view_draft_in_dashboard_application_any	none	-

View draft application details

Draft applications are those that have never been submitted, and have never left the first stage.

Human-readable name	System name	Default	Notes
View draft applications where they are the owner	view_draft_application_owner	user	Application creator can view details of draft applications.
View draft applications where they are the applicant	view_draft_application_applicant	none	By default, the subject of an application created on their behalf can't view it until it is submitted by the creator.
View user's draft applications	view_draft_application_user	none	-
View draft applications	view_draft_application_any	none	-

Edit and submit draft application

Draft applications are those that have never been submitted, and have never left the first stage.

Human-readable name	System name	Default	Notes
Edit draft applications where they are the owner	edit_draft_application_owner	user	Application creator can edit their own draft applications.
Edit draft applications where they are the applicant	edit_draft_application_applicant	none	By default, the subject of an application created on their behalf can't edit it until it is submitted by the creator.
Edit user's draft applications	edit_draft_application_user	none	-
Edit draft applications	edit_draft_application_any	none	-

Delete draft application

Draft applications are those that have never been submitted, and have never left the first stage. Only draft applications can be deleted; submitted applications can be withdrawn but not deleted.

Human-readable name	System name	Default	Notes
Delete draft applications where they are the owner	delete_draft_application_owner	user	Application creator can delete their own draft applications.
Delete draft applications where they are the applicant	delete_draft_application_applicant	none	By default, the subject of an application created on their behalf can't delete it.
Delete user's draft applications	delete_draft_application_user	none	-
Delete draft applications	delete_draft_application_any	none	-

View applications in the dashboard

Applies to non-draft applications (i.e. those that have been submitted at least once).

Human-readable name	System name	Default	Notes
N/A	~~view_in_dashboard_application_owner~~	-	Not implemented, owner can always view their own applications on the dashboard.
View applications in the dashboard where they are the applicant	view_in_dashboard_application_applicant	user	-
View user's applications in the dashboard	view_in_dashboard_application_user	staffmanager	-
View applications in the dashboard	view_in_dashboard_application_any	approver, manager	-
View user's pending applications in the dashboard	view_in_dashboard_pending_application_user	none	-
View pending applications in the dashboard	view_in_dashboard_pending_application_any	none	-

View application details

Applies to non-draft applications (i.e. those that have been submitted at least once).

Human-readable name	System name	Default	Notes
View applications where they are the owner	view_application_owner	user	-
View applications where they are the applicant	view_application_applicant	user	-
View user's applications	view_application_user	staffmanager	-
View applications	view_application_any	approver, manager	-
View user's pending applications	view_pending_application_user	none	By default, staffmanager can view details of a team member's applications. This capability limits the view to only applications they can immediately approve/reject.
View pending applications	view_pending_application_any	none	By default, an approver can view details of all applications on the same assignment. This capability limits the view to only applications they can immediately approve/reject.

Edit application

Applies to non-draft applications (i.e. those that have been submitted at least once).

Unsubmitted applications are those currently on form stages.

In approvals applications are those currently on approval stages.

First approval level applications are those currently at the first approval level in an approval stage.

Editing with these capabilities is always limited to the stage's defined form view – an approver being able to edit the application does not necessarily mean that they can change an applicant's answers, as this depends on how the workflow is configured. To edit all previously submitted fields in an application, use one of the edit_full_application capabilities in the next section.

Editing an application in an approval stage will reset it to the first approval level at that stage, unless one of the edit_without_invalidating_approvals capabilities in the next section is used.

Human-readable name	System name	Default	Notes
Edit unsubmitted applications where they are the owner	edit_unsubmitted_application_owner	none	Unsubmitted means currently on a form stage.
Edit unsubmitted applications where they are the applicant	edit_unsubmitted_application_applicant	user	-
Edit user's unsubmitted applications	edit_unsubmitted_application_user	none	-
Edit unsubmitted applications	edit_unsubmitted_application_any	approver, manager	-
Edit in-approvals applications where they are the owner	edit_in_approvals_application_owner	none	In approvals means currently in an approval stage.
Edit in-approvals applications where they are the applicant	edit_in_approvals_application_applicant	none	-
Edit user's in-approvals applications	edit_in_approvals_application_user	none	-
Edit in-approvals applications	edit_in_approvals_application_any	approver, manager	-
Edit user's pending submitted applications	edit_in_approvals_pending_application_user	staffmanager	By default, staffmanagers are allowed to edit team applications when those applications are pending their approval.
Edit pending submitted applications	edit_in_approvals_pending_application_any	approver	By default, approvers are allowed to edit applications, when those applications are pending their approval.
Edit first approval level applications where they are the owner	edit_first_approval_level_application_owner	none	First approval level means currently at the first level of an approval stage.
Edit first approval level applications where they are the applicant	edit_first_approval_level_application_applicant	none	By default, applicants cannot edit their applications once submitted, but this capability could be used to allow the applicant to edit their submitted application until it is approved by the first approver.
Edit user's first approval level applications	edit_first_approval_level_application_user	none	-
Edit first approval level applications	edit_first_approval_level_application_any	none	-
Edit user's first approval level pending applications	edit_first_approval_level_pending_application_user	none	-
Edit first approval level pending applications	edit_first_approval_level_pending_application_any	none	-

Special edit application capabilities

Applies to non-draft applications (i.e. those that have been submitted at least once).

These capabilities were originally intended for Workflow Managers, users who need to be able to fix stuck or incorrect applications without changing their state.

The edit_without_invalidating_approvals capabilities do not grant the ability to edit; they must be used in combination with edit_application or edit_full_application.

Human-readable name	System name	Default	Notes
Edit applications where they are the owner without invalidating exist approvals	edit_without_invalidating_approvals_owner	none	-
Edit applications where they are the applicant without invalidating exist approvals	edit_without_invalidating_approvals_applicant	none	-
Edit user's applications without invalidating exist approvals	edit_without_invalidating_approvals_user	none	-
Edit applications without invalidating exist approvals	edit_without_invalidating_approvals_any	manager	By default, a Workflow Manager can edit an application at any level of an approval stage, without resetting the approval process.
Edit full form on applications where they are the owner	edit_full_application_owner	none	-
Edit full form on applications where they are the applicant	edit_full_application_applicant	none	-
Edit user's full form on applications	edit_full_application_user	none	-
Edit full form on applications	edit_full_application_any	manager	By default, a Workflow Manager can edit any already submitted field in an application; they are not limited to fields in the current stage's form views.

Approve / reject application

Applies to non-draft applications (i.e. those that have been submitted at least once).

These capabilities all allow both approval and rejection of applications.

Human-readable name	System name	Default	Notes
Approve applications where they are the owner	approve_application_owner	none	-
Approve applications where they are the applicant	approve_application_applicant	none	-
Approve user's applications	approve_application_user	none	-
Approve applications	approve_application_any	manager	-
Approve pending applications where they are the owner	approve_pending_application_owner	none	Could be used to allow an approver to approve applications they created.
Approve pending applications where they are the applicant	approve_pending_application_applicant	none	Could be used to allow an approver to approve their own applications.
Approve user's pending applications	approve_pending_application_user	staffmanager	-
Approve pending applications	approve_pending_application_any	approver	-

Attach file to application

Applies to all applications.

If the stage has a form view with an editor field, this set of capabilities determines whether the user can upload files via the editor.

Human-readable name	System name	Default	Notes
Upload files to applications where they are the owner	attach_file_to_application_owner	user	-
Upload files to applications where they are the applicant	attach_file_to_application_applicant	user	-
Upload files to user's applications	attach_file_to_application_user	staffmanager	-
Upload files to applications	attach_file_to_application_any	approver, manager	-

Application comments

Applies to all applications.

Human-readable name	System name	Default	Notes
View comments on applications where they are the owner	view_comment_on_application_owner	user	-
View comments on applications where they are the applicant	view_comment_on_application_applicant	user	-
View comments on user's applications	view_comment_on_application_user	staffmanager	-
View comments on applications	view_comment_on_application_any	approver, manager	-
Post comments on applications where they are the owner	post_comment_on_application_owner	user	-
Post comments on applications where they are the applicant	post_comment_on_application_applicant	user	-
Post comments on user's applications	post_comment_on_application_user	staffmanager	-
Post comments on applications	post_comment_on_application_any	approver, manager	-
Post comments on user's pending applications	post_comment_on_pending_application_user	none	-
Post comments on pending applications	post_comment_on_pending_application_any	none	-

Withdraw application

Applies to non-draft applications (i.e. those that have been submitted at least once).

Unsubmitted applications are those currently on form stages.

In approvals applications are those currently on approval stages.

Human-readable name	System name	Default	Notes
Withdraw unsubmitted applications where they are the owner	withdraw_unsubmitted_application_owner	none	Unsubmitted means currently on a form stage.
Withdraw unsubmitted applications where they are the applicant	withdraw_unsubmitted_application_applicant	user	-
Withdraw user's unsubmitted applications	withdraw_unsubmitted_application_user	none	-
Withdraw unsubmitted applications	withdraw_unsubmitted_application_any	manager	-
Withdraw in-approvals applications where they are the owner	withdraw_in_approvals_application_owner	none	In approvals means currently in an approval stage.
Withdraw in-approvals applications where they are the applicant	withdraw_in_approvals_application_applicant	user	-
Withdraw user's in-approvals applications	withdraw_in_approvals_application_user	none	-
Withdraw in-approvals applications	withdraw_in_approvals_application_any	approver, manager	-

Backdate application

Applies to all applications.

Applies to all date fields in the application. Without one of these capabilities, the user may not choose a date in the past.

Human-readable name	System name	Default	Notes
Backdate applications where they are the owner	backdate_application_owner	none	-
Backdate applications where they are the applicant	backdate_application_applicant	none	-
Backdate user's applications	backdate_application_user	none	-
Backdate applications	backdate_application_any	manager	-

Browser not supported