Workflow application capabilities
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 | - | 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 | - | 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 | - | 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 | - |