Approval module

The approval system allows a form to go through approval stages where one or more users specified as approvers each choose to approve or reject the form.

[edit]

Goals

Obvious and easy to use for approvers making a choice
Automate as many parts as possible to require minimal management

[edit]

Overview

To use the approval module, a process template will contain one or more approval stages that are used by the forms. Each stage has a staff user defined as the intended approver. When the approver views a form that is eligible for their approval, they are presented with a clear choice of approve or reject. This response is permanently recorded on the form.

Each approver can make one choice per pass. When a pass is completed it will have a result of approved or rejected. Until it is completed, a pass has a result of pending. The process setup determines the result conditions such as unanimous or majority. The template can further be setup to abandon the pass as soon as rejection is assured. The intention is that someone will then make changes to the form to get an approval in the next approval pass. The settings also allow for templates that only go through one pass and then that's it, the form is approved or rejected forever. A form is considered to have the same result as its most recent completed pass. If a form doesn't have a completed pass then it's pending.

Approval stages have settings that may be able to determine the approver automatically from references in the form. Otherwise, the approver is chosen manually within the form or simply setup to always be a certain user. The stages also have optional settings to control when they are eligible. This is done by status level and by optionally requiring that approval stages are completed in order. Within a form a stage can be manually skipped or possibly automatically skipped depending on a staff reference in the form.

[edit]

Architecture

Approval stages are added, edited, and deleted in the template. The forms don't have their own copy of each stage, but they do have their own approver defined for each stage that overrides the choice in the template. The reason for this design is that the template may not specify a specific user as the approver for a stage, but may say that it depends on a field in the form or is to be chosen when needed.
Each form has passes and each pass has responses. Each response is also linked to an approval stage to ensure that stage isn't eligible again within the given pass. The response has it's own staff reference and stage name which it takes from the stage when the choice is made. Editing or even deleting an approval stage will not affect existing responses. Neither will changes to the form like selecting a different staff user for a field or stage, or skipping a stage.
Each approval stage can only create a single response per pass. The pass records when it is completed and what the result is. Every form starts with one pass. When a pass is completed a new one may be created automatically depending on the template options.
The approval module can be turned off per subscriber (default is "On")

[edit]

More terminology

Approver: The user who will submit a choice for an approval stage.
Choice: "Approved", "Rejected", "Skipped", or "Pending".
Eligible: If the conditions are met in a form for an approval stage, then the approval stage is eligible for a choice to be made by the approver.
Eligible approver: A user who is specified as the approver in a stage that is eligible for the form.
Path: A set of 3 status level options that define a course for a form to take when being approved. An eligible status, a status to move to on an approved result, and a status to move to on a rejected result. Only one path is required to use the approval module, but more may be added.
Response: The single choice of an approver in a pass.
Result (pass): "Approved", "Rejected", "Aborted", or "Pending".
- An pending pass always has a pending result. Once a pass is complete, the template approval condition settings are used to determine the result of "Approved" or "Rejected". Aborting a pending pass makes it complete with a result of "Aborted".
Result (form): "Approved", "Rejected", or "Pending".
- The form is always "Pending" when it is eligible for approval.
- Otherwise the form result is the result of its most recently completed pass that doesn't have an aborted result.
- If there isn't a completed pass with an approved or rejected result then the form result is "Pending".
- That means all new forms start out with a result of "Pending".

[edit]

Examples

See Approval module examples (Incomplete)

[edit]

Template setup

New tab in the template settings along with Fields, etc. It has 3 boxes, "Info", "Paths", "Stages".

[edit]

Toolbar

"Check stages"
- This manually triggers a check for approvers then auto-skip then eligibility for each stage in each form.
- This shouldn't be needed since those checks should be triggered automatically by any change that can affect them, but is provided in case there was an error or other problem that interrupted a long check.

[edit]

Options

Options set for the entire process in an "Info" box.

Enabled: Yes or no for the approval module for the process.
- Default is "No".
- Changing a process using approvals to no doesn't delete anything, it just hides everything to do with approvals in the forms. Approval setup in the template is not affected. For example, a user can still add paths and stages to the template while approvals are disabled.
- Enabling approvals for a process may take some time to execute as it must recheck every form for stage eligibility and auto-skip.
Lock editing: Yes/No. Yes means users are prevented from editing the form (including changing the status level) if there are eligible approvers.
- Default is "No"
- See Edit lock
Add note. Yes/No. Determines if a note is added when a choice is made.
- Default is "No"
Approved condition: What choices does it take to make a pass result approved? Radio buttons:
- Unanimous: Every approval stage must choose approved in the pass (default).
- Majority: More than half must choose approved.
- Single: Just one needs to approve it.
Pass completed: Radio options
- When all respond: Every approver must respond.
- When possible: Depends on the condition: (default)
  - Unanimous: The first reject or everyone responding completes the pass.
  - Majority: Once half the approvers reject, or half + 1 approves, or everyone responds completes the pass.
  - Single: The first approval or rejection completes the pass.
Start next pass: Drop down options
- "Always": When a pass is completed a new one is started
- "If rejected or aborted": (default) When a pass is completed and the result is rejected or aborted then a new pass is started.
- "Never": Don't auto-start the next pass. Must be done manually if another pass is needed.

[edit]

Paths

Listed in a grid in a "Paths" box.

Grid style (with headers)
- Sorted by "Eligible" status column as per the template status order
- No user sorting
Columns:
- Eligible
- On approval
- On rejection
- ("Edit" link)
- ("Remove" link)

If there are no paths show a warning. "At least one path is required to use the approval module".

[edit]

Path add/edit

Added & edited on a dedicated page.

Eligible: Status level.
- Drop down of status levels listed in the template order.
- Status levels already used as eligible status for other paths aren't listed as options. In other words, path eligible status must be unique and we enforce that by filtering the options.
- If all status levels have been used in paths then trying to add another pass shows the wizard with an error and just the cancel button. "All status levels are in use."
- Default is the first status level in the list
- Required ("n/a" is not an option)
- Can't be changed on existing paths. When editing it is displayed as a label.
On approval: Status level.
- Drop down of status levels listed in the template order.
- Default is the first status level in the list
- Required ("n/a" is not an option)
On rejection: Status level.
- Drop down of status levels listed in the template order.
- Default is the first status level in the list
- Required ("n/a" is not an option)

Only the eligible status has to be unique. It's fine if different paths use the same approved or reject status. It's even fine if a path uses the same status for approved and rejected.

[edit]

Stages

Listed in a grid in a "Stages" box.

Grid style (with headers)
- Sorted by stage name A-Z
- No user sorting
Columns:
- "Stage"
- "Approver"
  - "User: {staff user}" or
  - "Field: {staff ref field}" or
  - "n/a" (for "Select when needed")
- "Eligible after"
- "Comment"
- "Skip if" (blank) or {field}{" is "/" isn't "}{role}{" or "}{field}{" is the approver"}
- ("Edit" link)
- ("Delete" link)

If there are no stages show a warning. "At least one stage is required to use the approval module".

[edit]

Stage add/edit

Added & edited on a dedicated page.

Stage name: This is a label to describe the stage. It can also be used to set the display order since stages and responses are listed sorted alphabetically by stage name.
- Referred to in column headers and info labels as just "Stage".
- Required and must be unique across all approval stages within the template
- Limit to 64 characters
Approver. There are 3 options for who the approver will be and one is chosen by radio buttons.
- Staff user. Chose a staff user from the drop down list. Only staff users in a role that is not hidden from this process are listed.
- Reference field. Chose a staff user reference field from the drop down list. This option can't be selected if there are no applicable fields.
- Select when needed. ("n/a") Don't specify an approver here. Someone will have to chose one in the form.
- Default is "Select when needed"
Require comment on. Drop down select that determines when an approver's choice needs a comment from them as well:
- "Approval"
- "Rejection"
- "Both" (default)
- "Neither"
Eligible after. Optional approval stage that must have a response for this pass before this approval stage is eligible.
- List of approval stages in this template by stage name A-Z
- Default is first option, "n/a".
Enable auto-skip: Yes/No enables the auto-skip feature for this stage.
- Default is "No"
- See Skip
Skip if
1. Drop down list to select a staff reference field.
  - Default is first option, "n/a".
2. Drop down list to select "is" (default) or "isn't"
3. Drop down to select a staff role
  - Default is the first role, alphabetically

[edit]

Per form

[edit]

Approver

Each form has a staff user set as the approver for each approval stage in the template
The approver may be null:
- This happens if:
  - The approval stage has an approver option set to a field that is null or missing.
  - The approval stage has an approver option of n/a ("Select when needed").
  - A previous selected staff user is deleted (see Delete)
- This is something that needs to be watched out for. In the future we may build some sort of warning system, but for now a user will just need to check up on a view using the "Approver missing" filter (see More display)
If the approver option is set to a staff reference field that exists, then editing that field (including by import or starting a form) will set the approver to the value of the field.
- The change is made even if the stage already has an approver for this form (this is a change from the original rule of only updating if the approver was n/a)
- That means changing the value of the field again WILL change the approver again.
- This also means that changing the value of a field WILL set the approver if someone had gone in and already manually set the approver for that stage.

[edit]

Skip flag

For each stage each form has a skip flag.

See Skip below

[edit]

Approver and auto-skip triggers

Approver assignment by staff reference and auto-skip are checked when:

A staff reference field is edited or filled in because of a form start, import, copy, edit, synchronization, or the field is deleted/restored in the form.
A staff user is deleted/restored. This may affect a stage directly or through a staff reference.
A staff role is deleted/restored. This affects the auto-skip setting for stages.
An approval stage is added, edited, deleted, or restored in the template (check every form)
A manual check is run for a form by clicking "Check stages" on the template page

[edit]

Responses

When an approver makes a choice, a response is created. A response is intended to be a permanent record. There can only be one response per approval stage per pass.

Data

Approver
- Since the approver for a stage for a form can change, the response keeps its own record of who the approver was that made the choice.
Choice
- "Approved", "Rejected", or "Skipped"
When
- The datetime the choice was made.
Comment
- Text string that may have been entered by the approver.

Rules

Responses can not be edited, deleted, or manually created.

[edit]

Passes

Number: Each pass in a form gets a consecutive integer starting with 1 for the first pass.
Started
- datetime
Completed
- datetime
Result
- "Approved", "Rejected", or "Pending"
- This is the overall result of pass based on the approval conditions defined in the template and the various responses in the pass.

Rules

Only one active pass at a time per form.

[edit]

Form approval box

Title of "Approval"
Toolbar:
- "Manage" link to Form approval management page
For each pass:
- H2 header with "Pass {#}: {RESULT}"
  - Shows the pass count with the result of the pass "Pending", "Approved", or "Rejected"
  - Example: "Pass 1: Pending"
- List each stage in a grid
  - gridList style meaning no headers
  - Columns: stage name, approver, response choice
  - Sort A-Z by stage name. No user sorting.
  - If the approver is null and the stage is not skipped show a small warning icon before the "n/a"
  - If the approver hasn't made a choice yet this pass show "Pending" for the result. Otherwise show "Approved" or "Rejected". Or...
  - If the stage is skipped then show each cell with an "na" CSS class and put "Skip" in the result.

[edit]

Form approval management page

Two boxes, "Stages" and "Passes"

[edit]

Stages

Grid of approval stages

Columns
- Stage
- Approver
- ("Edit" link)
- ("Skip" or "Activate" link)
If the stage is skipped then show the stage name and approver cells in the "na" CSS class.

[edit]

Stage skip/activate

See Skip

[edit]

Stage approver edit

Clicking "Edit" goes to a 1 page wizard that allows a different approver to be selected.

There is an "n/a" option
Doesn't affect existing responses
- Example: John was the approver and made a choice. A new pass has not been started yet, but I go in to the approval management for the form and change the approver for this stage to Mary. Mary will not get a notification because she's not eligible because this stage already has a response in the current pass. That response says John since it made its own copy of the approver when the choice was made. If a new pass is started, Mary will get a notification once her stage becomes eligible again.

[edit]

Passes

A grid of responses for each pass. Each pass displays the start and complete datetime then is followed by a grid.

Columns
- Stage
- Approver
- Choice
- Comment
- When
Sorted A-Z by stage name. No user sorting.

[edit]

Passes toolbar

"Abort pass {#}"
- Shown if there is a pending pass
- Aborts the pass
"Restart pass {#}"
- Shown if:
  - There isn't a pending pass, and
  - The last completed pass was aborted
- It's an undo for the abort
- Makes the last completed pass pending again.
"Start pass {#}"
- Shown if there isn't a pending pass
- A new pass is started

If there is a pending pass then the abort link is shown. If there isn't a pending pass then the start link is shown and possibly also the restart link.

[edit]

Skip

Sometimes a stage needs to be skipped for a form. There are two methods to skip a stage, manual and auto-skip.

Skipped stages work by automatically making a response that contains a choice of "Skipped" when they become eligible.

[edit]

Flag

Per form any approval stage can be flagged to be skipped. This is called the skip flag.

A stage that isn't set to be skipped is referred to as "active".
A stage with a skip flag will generate a "Skipped" response as soon as it becomes eligible.
Existing responses are not affected when setting a stage to be skipped. The stage will just be skipped the next time it becomes eligible.
If a stage is eligible but there is no response yet, skipping the stage will not only set the flag, but also register a "Skipped" response immediately for the pending choice.

[edit]

Manual

To manually set a skip flag the user clicks "Skip" for the stage on the Form approval management page.

[edit]

Auto-skip

The approval stage may have been setup with auto-skip enabled. If it is then either of two conditions will cause the stage to be skipped when it becomes eligible:

Is there a staff user in the form that is or isn't a certain role? A staff reference field and role are specified along with an is/isn't operator. If a field is specified and the field has a staff value then that user's role is checked against the specified role.
Is there a staff user in the form that is this approver? Another staff reference field can be specified to check against the specified approver for this stage. If a field is specified and the field has a staff value and that staff is this approver then the stage is skipped.

[edit]

Activating

Stages with a skip flag (by either method) are displayed as such on the Form approval management page and the skip link is replaced with an "Activate" link that will remove the flag.
Manually removing the skip flag doesn't prevent it from being set again manually or automatically. For example, if a stage is auto skipped then activating it without changing the staff reference field or role membership that led to the skip will just mean it will get auto-skipped the next time a change triggeres the check.

[edit]

Response and result

"Skipped" responses are not counted towards the total responses for a pass when determining the pass result. In other words, for determining unanimous or majority it's like the skipped results don't exist.
If all the stages have been skipped it is the same as when there are no stages, the pass is considered to still be pending.
- If we allowed all skip to cause a rejected or approved result then we open up the possibility of an infinite loop.
See Making a choice below.

[edit]

Edit lock

If the lock editing option is "Yes" then the form will be locked if it is at a status level that is eligible for any approval path.

Reason message: "Eligible for approval"

[edit]

Eligibility

An approval stage in a form is eligible if all the following are satisfied:

It has an approver.
There isn't a response yet for this stage for the current pass.
If it has an "Eligible after" then the specified stage must have a response for the current pass.
If the status level of the form is an "Eligible" status of a path
Approvals must be "Enabled" for this process.
The approval module must be on for this subscriber.

[edit]

Eligibility check

Eligibility is saved as a flag in the form per stage. An eligibility check must be done when:

Staff reference field value change by form start, edit, copy, import, synchronization or the field is deleted/restored in the form.
- Eligibility check is done after the auto-skip and approver values are checked.
- Can affect the approver
- Can affect an auto-skip
Deleting/restoring a staff user
- Can affect a staff reference field value (see above)
- Can affect the approver directly
Delete/restore a status level in the template
Change status of the form
A response is made for a stage in the form
A pass is started in the form
Direct edit of an approver for the stage in the form
The approval stage is skipped/activated for the form
The "Check stages" is run for the template
Add, edit, delete, or restore an approval stage in the template
- Unless only the name or comment option was changed.
Add, edit, or remove an approval path in the template
Edit template approval options
Approvals are enabled for the process
The approval module is turned on for the subscriber

In cases where the change also triggers a check for approver assignment or auto-skip then those checks must be run as well.

[edit]

Making a choice

[edit]

Viewing the form

The approval system must allow approvers to see a form and make a choice without necessarily being a participant.

This will be done by changing the limited read and limited edit process permissions to also allow users who are an approver in an eligible approval stage in the form to view that form. In other words, a staff user with one of the limited permissions can see a form if they are a participant or if they are an eligible approver.
This gives the designer the power to limit approvers to just making choices when needed. The system also allows the designer to give the approver full access to the form or make them a participant.
This does not change the rules for editing a form. Being an eligible approver gives a user another way to view a form, but no new ways to edit a form. This is desirable because it allows the user to have approvers that can only make a choice. See Choice below.
This means that approvers must belong to a role that at least has limited read. If the process is hidden for a user then they won't be able to see the form to make a choice.
See Security

[edit]

Choice

If a user is viewing a form and they are an eligible approver then they see the approval choice control.

The approval choice control is shown above the boxes as a wide, large control that is impossible to miss.
The control has a brief explanation, the stage name(s), and two buttons:
- "Approve" and "Reject"
Clicking either button goes to a confirmation page.
- If this stage is set to require a comment for the given choice then the confirmation page shows a text area for the comment.
- The confirm page has a "Cancel button" to return to the form without making a choice
- The confirm page also has an OK button that changes its display (value) depending on the choice to either show "Approve" or "Reject"
It's possible that in between showing the user the buttons and the actual click that something could be changed that makes the user no longer eligible.
- Show the general error page: "Your approval result could not be saved"

[edit]

Multiple eligible stages

If the user is an approver for multiple eligible stages then the choice they make is applied to all the stages creating multiple results.

The stage name(s) shown over the choice buttons and on the confirmation page is a list control. In ideal situations only one stage will be shown, but in the case of multiple eligibility for one user, the applicable stage names are listed in A-Z order separated by a comma and space.

[edit]

Response

When an approver makes a choice, a response is created.

Create response
Add note if required by the settings
- If the stage is setup to create a note but not ask for a comment then the following preset text is used:
  - If approved: "Approved"
  - If rejected: "Rejected"
- The note author is the approver
- It's added to the form's "Notes"
- A note is not added if the response is "Skipped"
Create history entry
Check if pass is completed. Depends on template option:
- "When all respond": If all the stages have a response in this pass then it is complete. Otherwise it is not complete.
- The exception is if all the responses are "Skipped" then the pass remains "Pending" and is not complete.
- "When possible":
  - Unanimous: The first "Rejected" choice completes the pass.
  - Majority: If half + 1 of the stages (don't count "Skipped" responses) have now made an "Approved" choice or half of the stages have now made a "Rejected" choice then the pass is completed.
  - Single: The first "Approved" choice completes the pass.

[edit]

No stages

If there are no stages or all the stages were skipped then the pass is not considered complete.

[edit]

Abort

Anything that aborts a pass means the pass is completed with an "Aborted" result.

[edit]

Result

If the pass is completed (approved, rejected, or aborted):

Determine the result
Create a history entry
Change the form status level depending on the on approval or on rejected status setting of the path with the eligible status that the form was at.
- The status level is not changed if the result is "Aborted"

[edit]

Form history

See Form history (spec)

An approver making a choice and a possible comment generates one history entry.
Ignoring or allowing (un-ignoring) a stage in a form creates one history entry.
A pass completing creates one history entry
A pass aborting creates one history entry
If the status of the form is changed because of a pass result then the history entry for the status change will be an "auto" method just like a status change from a status trigger.
Selecting an approver either directly or through a staff reference does not create a history entry since it doesn't mean anything until a choice is made.

[edit]

Force approval

A staff user with the permission to manage the approvals of a form can also force the result of a pass if the form is pending.

"Force result" link in the approval box beside "Manage" when the form is pending.
Launches a wizard that works a lot like the regular approval choice UI. It has an optional comment box and the Approve and Reject buttons. It also has a Cancel button.
The same rules apply for copying the result + comment to the notes.
Any existing responses stay the same and any pending stages are marked as skipped.
The Form history gets a "Forced" entry then the "Completed" entry.

[edit]

Delete

[edit]

Stage

Recycle bin:
- Type: "Template approval stage"
- Name: "{template}: {stage name}"
  - Example: "Order: Final approval"
- Don't allow restore if stage name exists in that template.
Other stages:
- If set as "Eligible after" value for other stages then set that value to "n/a".
- Reversed on restore unless a new value has since been chosen.

[edit]

Path

No recycle bin or restore.
Existing passes are not affected, however, an eligibility check must be run to see if with that path gone some previously eligible stages no longer are.

[edit]

Staff user

Approval stages in the template and approvers in the form:
- Approvers set to the deleted user are replaced with the user who deleted them
- Reversed on restore if the user is restored unless the approval stage was since changed again to someone else.
Responses:
- Show "n/a" for approver.
- This is acceptable since the approver name will be remembered in the form history and we certainly don't want to replace them with someone else since this is a record of a vote.
- Reversed if the user is restored.

[edit]

Staff role

Approval stages in the template:
- If the field was set as an "Approver" or as part of the "Auto-skip" settings then the value becomes "n/a".
- This is not reversed on restore as deleting a role is considered to be semi-destructive action.

[edit]

Template field

Approval stages in the template:
- If the field was set as an "Approver" or as part of the "Auto-skip" settings then the value becomes "n/a".
- Existing forms that already have an approver chosen for a pending stage because of a field maintain that approver. However, the link between the stage and the field (which the form may still have), is now gone.
- This is reversed on restore as long as a different field has not since been chosen.

[edit]

Status level

Paths:
- Paths that used the status level for any of the 3 options are deleted. (see deleting a path, above).
- This is not reversed on restore.

[edit]

More display

[edit]

Process view filters

Listed in an "Approval" filter group.

Approval required by
- "me" or "someone"
- someone: Does the form have an eligible approval stage
- me: Does the form have an eligible approval stage where this user is the approver
- Similar to the "Action required by" filter
Approval result
- "Approved", "Rejected", or "Pending"
- Uses the result of the most recently completed approval pass or pending if there hasn't been a completed pass yet.
Approver missing
- No additional values
- Forms that have one or more stages that are missing the approver and are not flagged to be skipped.

[edit]

Process view columns

Listed in an "Approval" column group.

Approval result
- "Approved" or "Rejected" or "Pending"
- Shows the form approval result.
Approval result (date)
- The date of the latest form approval result change. New forms with no result yet show the form creation date.
Approval pass
- Shows the number of the most recent pass including pending passes.
Eligible approvers
- Lists the approver from any eligible stages.
- Separate by comma and space if there are multiple
- Don't list a single staff user more than once (since it's possible for the same user to be the approver in more than one approval stage for a form).
- If there are no eligible stages show a blank
Eligible stages
- Lists any eligible stages.
- Separate by comma and space if there are multiple
- If there are no eligible stages show a blank
Eligible (date)
- Most recent date a stage became eligible
- If there are no eligible stages show a blank
(each stage)
- Listed by stage name
- Shows the name of the approver or blank

[edit]

Eligible columns business goals

Eligible approvers = who are we waiting for
Eligible stages = what stage are we waiting at
Eligible (date) = how long have we been waiting

[edit]

Attention list

Indicate forms that have an eligible approval stage where the approver is this user.
- Example: "4 approval required"
- This count does include archived forms.
- Links to a new built-in view "Approval required by me" that uses the new approval required filter. This view does include archived forms.
- Similar to action required

[edit]

Repeating fields

Only reference fields in the master form affect the approvals. Set forms (repeating fields) are ignored.

[edit]

Technical notes

The choice should not be designed in the business or database as a boolean.
- For one thing, it needs to have a null value when a choice hasn't been made.
- Further, keeping it as an enumeration, key, etc. leaves open the possibility for more choice options beyond just approve and reject in the future.

[edit]

Security

[edit]

Staff users

Template setup approval tab & page
- processes.design.approvals
- Requires the approval module
Form approval management page & controls
- processes.form.infoEdit.approvals
- In addition to the approval module, this new group requires a new role privilege: "Manage approvals". List it with the other process privileges under "Import forms".
Form
- processes.form
- Existing limitedRead check is being changed to allow users who are either a participant or an approver in an eligible approval stage.
- The control to make a choice is only shown to the actual user that is an approver in an eligible approval stage.
- See Making a choice
Form approval box
- processes.form.approvals
- Requires the approval module and approval enabled for the template
Forms views approval columns
- processes.approvals
- Requires approval module and approval enabled for the template

[edit]

Agent users

[edit]

Customer users

[edit]

History

Judge: Feature added
Supercharger: Force approval option

[edit]

Future

More advanced lists and conditions for automatic approver selection and auto-skip.
Template download/import support
Agent and customer users

Retrieved from "http://rpmsoftware.com/wiki/index.php/Approval_module"

This page was last modified 20:17, 2 Sep 2009.
This page has been accessed 3179 times.

History