File Approval
Overview
RPI optionally supports approval processes for two file types (offers and interactions).
When approval is enabled for offers, you cannot execute an offer activity based on an offer that does not have an approved version. If the current version of an offer is not approved, but a previous approved version exists, the latter will be used at offer activity execution.
(For details of versioning within the RPI file system, please see the RPI framework documentation.)
When approval is enabled for interactions, you cannot execute an interaction workflow in production mode unless the interaction within which it exists is approved.
Approval of a file can be requested by any user, but only those users designated as approvers have the ability to approve or deny approval in respect of a file. The rules governing the requirements for approval of a given file type are configured on a file type-by-file type basis.
A number of approval statuses support the RPI file approval process:
Not approved
Approval requested
Awaiting approval
Approved
Approval denied
Each of these is documented separately.
File approval touches upon a number of areas, each of which is also documented separately:
File System – Approve File functional permission
File Type Approval configuration interface
Approval panel
Manage File Approval dialog
Interaction Designer – file approval ramifications
File Approval widget
Operations Interface – Approval Summary tab
Approval auditing
Approve File Functional Permission
The File System – Approve File functional permission is available when configuring user groups in the User Groups configuration interface.
It is used to grant to users the ability to approve files. If a user is a member of a user group associated with the functional permission, and that user group is in turn associated with the file type approval record for a given file type, then that user is deemed to be an approver for the file type in question. He or she may approve files of that type and deny approval in respect of the same.
Note that the ability to request approval of a file is not controlled by this functional permission, being open to all RPI users.
File Type Approval Configuration Interface
A dedicated configuration interface (File Type Approval) is provided in the Configuration Workbench. Its purpose is to control whether file approvals are enabled or disabled for the file types for which approvals are supported (currently limited to offers and interactions), and also to define the approval criteria that govern each.
Full details of the interface can be found in the Configuration Workbench documentation.
Approval Panel
The approval panel is the primary mechanism by which file approval is requested, granted and denied.
It is found to the right of the toolbar in the Interaction and Offer Designer.
The approval panel is displayed when approval is enabled for the file type in question, once a file has been saved for the first time.
The approval panel consists of the following elements:
Approval Status
The color used provides an indication of the current file version’s approval status. The panel’s background appears:
White if approval status is Not approved:
Orange if approval status is Awaiting approval or Approval required:
Green if approval status is Approved
Red if approval status is Approval denied
Current Version
Details of the current version of the file being displayed are always shown in the main and mini approval panels.
In the main panel, an icon indicates the file’s type. The current version number is shown, as is the file’s current approval status.
A tooltip is shown when you hover over the version number:
Open Latest Approved Version
This is displayed at the main approval panel when the version of the file currently being viewed is not approved, and another, approved version of the file exists (if several approved versions exist, the most recent is referenced in this context).
If you are viewing an offer, Open latest version is a button, and you can click it to open the latest approved version of the offer in a new Offer Designer instance (note that it is not possible to open a previous version of an interaction, and, as such, a non-clickable icon is shown instead of a button in the Interaction Designer). If the version of the offer in question is already displayed, it receives the focus.
Open Latest Version
This button applies to offers only and is displayed at the main approval panel when the version currently being viewed is not the latest, and the latest version of the file is not approved.
Clicking the button displays the latest version of the offer in a new Offer Designer instance. If the version of the offer is already displayed, it receives the focus.
Request Approval
This button allows you to initiate the file approval process for the file you are currently viewing.
The button is displayed when the file has been saved and no outstanding changes exist within it. If you attempt to invoke Request Approval when the file is invalid, a warning message is displayed.
Invocation of Request Approval displays the Request File Approval dialog.
If you wish, you can enter an optional comment to accompany your file approval request (the comment can be a maximum of 1000 characters in length).
You can then click Continue, which sets the file’s status to Awaiting approval, and displays the Revoke Approval button. A direct pulse notification is sent to all potential approvers (notifications are not sent if system configuration setting EnablePulseMessages is set to False). If a potential approver is logged in, he or she receives a desktop notification.
Note that, from the potential approver’s perspective, the file’s approval status is Approval required.
An email notification (entitled 'Approval request') is also sent to all potential approvers:
'A request has been made by [Approval requester] to approve the file '[filename]''
'[Comments]'
'File details:'
‘Server’
'File name'
'File type'
'Version'
‘Online approval link’
‘Links For Review’
If an email offer was staged at its approval request, the email also contains a Links for Review section, which lists each staged file’s URL. The recipient can click each hyperlink to review the email’s content in his or her default browser. The same section is also included in the email sent on a file’s approval being re-requested.
If the file type’s approval criteria are defined such that they cannot be met (due to there being an insufficient number of users in the pool of potential approvers), a warning message displayed ('There are insufficient users to meet the minimum required approvers configured for this approval type').
If you elect not to proceed with launching the file approval process, you can click Cancel, which removes the dialog from display without proceeding with the approval request.
Revoke Approval
This button is used to cancel a request for approval made by the current user.
The button is displayed when the file’s approval status is Awaiting approval, and when approval was requested by the current user.
Invocation of Revoke Approval displays the Revoke File Approval Request dialog.
If you wish, you can enter an optional comment to accompany your file approval revocation request (the comment can be a maximum of 1000 characters in length).
You can then click Continue, which sets the file’s status to Not approved and displays the Request Approval button. A direct pulse notification is sent to all potential approvers (notifications are not sent if system configuration setting EnablePulseMessages is set to False). If a potential approver is logged in, he or she receives a desktop notification.
An email notification (entitled 'Approval request cancelled') is also sent to all potential approvers:
'The request to approve the file [filename] has been cancelled by [Approval requester]: [Comments]'
'File details:'
‘Server’
'File name'
'File type'
'Version'
‘Online approval link’
Note that, if you attempt to revoke an approval request in respect of a file with an approval status that has changed to other than Awaiting approval, a warning message is displayed:
'The file is no longer in a state to cancel the approval request. Your approval status may need to be refreshed'.
If you elect not to proceed with revoking the file approval request, you can click Cancel, which removes the dialog from display.
Resend Request
This button is used to remind those potential approvers who have yet to respond that approval of a file remains outstanding
The button is displayed when the file’s approval status is Awaiting approval. Note that you do not have to have initiated a file’s approval in order to invoke Resend Request.
Invocation of Resend Request displays the Revoke File Approval Request dialog.
If you wish, you can enter an optional comment to accompany your resending of the file approval request (the comment can be a maximum of 1000 characters in length).
You can then click Continue, which sends a direct pulse notification to all potential approvers (notifications are not sent if system configuration setting EnablePulseMessages is set to False). If a potential approver is logged in, he or she receives a desktop notification.
An email notification (entitled 'Approval request’) is also sent to all potential approvers:
'This is a reminder from [Approval requester] that the file [filename] is awaiting approval]: [Comments]'
'File details:'
‘Server’
'File name'
'File type'
'Version'
‘Online approval link’
If you elect not to proceed with sending the reminder, you can click Cancel, which removes the dialog from display.
Note that Resend Request need not be invoked by the user who originally requested the file’s approval – it could, for example, be used to send a reminder by an approver to another approver whose approval remains outstanding.
Approve
This button allows you, as an approver, to grant your approval in respect of the file you are currently viewing
The button is displayed when the file’s Approval status is Approval required. The current user must be a member of a user group associated with the File System - Approve File functional permission, and the user group must be associated with the File Type Approval record for the file in question.
Note the list of a file’s potential approvers is set at the point at which the approval request is made. If changes to the pool of candidate approvers occur, it is necessary to cancel the original approval request and re-request approve to ensure the changes are taken into account.
Invocation of Approve displays the Approve File dialog.
If you wish, you can enter an optional comment to accompany your approving the file (the comment can be a maximum of 1000 characters in length).
On clicking Continue, the file’s approval status is updated:
If all of the file’s approval criteria are satisfied, its approval status is set to Approved. The file’s version is incremented to the next major version (e.g. a file previously at version 0.1 becomes version 1.0…note that a new version is not created at this point, as the file itself has not changed, and, as such, version 0.1 is no longer accessible).
If a file’s approval criteria not satisfied, its approval status is set to Awaiting approval.
A direct pulse notification is sent to all other potential approvers (notifications are not sent if system configuration setting EnablePulseMessages is set to False). If a potential approver is logged in, he or she receives a desktop notification.
An email notification is also sent to all potential approvers:
If all file approval criteria are satisfied:
‘The file '[filename]' has been approved’
If file approval criteria are not satisfied:
'[Approver] has approved the file [filename]'
[Comments]
'Now waiting for [n] more approver(s)'
A pulse and advisory email are also sent to the approval requester. In addition to the detail included in the previous pulse message and email, the following are also included:
Approver details
Username
Status
Response date
If you elect not to proceed with granting file approval, you can click Cancel, which removes the dialog from display.
When attempting to approve an email offer when the Offer file type approval’s Require staged offers property is checked, the offer must be staged for review prior to being approved. If you attempt to approve an email offer that has not been staged in this context, a warning message is displayed.
Deny
This button allows you, as an approver, to deny approval of the file you are currently viewing
The button is displayed when the file’s Approval status is Approval required. The current user must be a member of a user group associated with the File System - Approve File functional permission, and the user group must be associated with the File Type Approval record for the file in question.
Invocation of Deny displays the Deny Approval dialog.
If you wish, you can enter an optional comment to accompany your denial of file approval (the comment can be a maximum of 1000 characters in length).
On clicking Continue, the file’s approval status is updated:
If file type approval criteria can no longer be satisfied (e.g. Everyone must approve or an insufficient approvers remain available), the file’s approval status is set to Approval denied.
If file type approval criteria are still able to be satisfied (i.e. there remain sufficient approvers to meet the approval criteria), its approval status remains at Awaiting approval.
A direct pulse notification is sent to the user who requested approval of the file (notifications are not sent if system configuration setting EnablePulseMessages is set to False). If the user is logged in, he or she receives a desktop notification.
If the file’s approval status was set to Awaiting approval, the pulse states:
'[Approver] has denied the approval of file '[filename]. Waiting for [n] more approver(s)'
If the file’s approval status was set to Approval denied, the pulse states:
'The approval of file [filename] has been denied: [Comments]'
An advisory email (entitled ‘File approval denied’) is also sent to the approval requester. In addition to the contents of the pulse message, the following are also included:
Approver details
Username
Status
Response date
If you elect not to proceed with denying file approval, you can click Cancel, which removes the dialog from display.
One Click Approval
‘One click’ file approval is supported, and is enabled when all of the following conditions are satisfied:
File type approval is enabled for the current file type.
The current user is a member of an approval user group.
Self-approval is enabled.
One of the following conditions is met:
Everyone in the approval user group(s) must approve, and the current user is the only member of the group(s).
At least the following number of users must approve is set to 1.
The current user has the File System – One Click Approval functional permission.
If the one click approval conditions are satisfied, on invocation of Request Approval, the Request File Approval dialog is displayed; on clicking Continue at the same, the file’s approval status is set immediately to Approved.
If one click approval conditions are not satisfied, the file’s approval status is set to Awaiting approval.
Dependent Files Changed Warning Indicator
A warning triangle indicator is used to advise you that a file upon which the current file depends has been saved since approval was requested for the current file.
The warning indicator is displayed in the following circumstances:
The current offer version contains one or more assets, smart assets or attributes that have been modified since the offer was approved.
The interaction contains one or more offers containing assets, smart assets or attributes modified since the interaction was approved, or one or more other files (e.g. audiences) modified since the interaction was approved.
Clicking the triangle displays the Modified Dependent Files dialog.
Modified dependent files are listed. For each, the following are displayed:
Icon
Name
When you hover over a dependent file, an Open latest version button is displayed. Invocation thereof displays the file in question in an appropriate designer (unless non-navigable (e.g. an attribute)).
When you are viewing an email or SMS offer containing modified dependent files, viewing a preview of the final offer content takes into account the latest state of the modified dependent files. However, you can also invoke Open latest approved version to view the offer content at the time of approval (note that the resultant offer version will have the same version number as the current version, even though the rendered content differs).
View/Manage the Approval of this File
This button is shown to the right of the main approval panel:
Invocation displays the Manage File Approval dialog (covered separately).
Implicit Approval Cancellation
If you change and save file with an Awaiting approval approval status, a direct pulse notification is sent to its potential approver(s) (notifications are not sent if system configuration setting EnablePulseMessages is set to False).
An email (entitled ‘Approval request cancelled’) is also sent.
Auto-Refresh
The approvals panel is auto-refreshed every 10 seconds, meaning that a user who requested a file’s approval can be automatically made aware of a change in its approval status if the file is currently open.
Manage File Approval Dialog
The Manage File Approval dialog is accessed via the View/manage approval of this file button, shown to the right of the approval panel.
It is a non-modal dialog that provides a summary of the current approval status of the file in respect of which it was invoked. The dialog contains the following:
Refresh Approval Status
A Refresh button is shown to the top right of the dialog.
Clicking it immediately updates the file’s approval status as displayed at the Manage File Approval dialog, and, if open, also in the underlying designer in which the file version shown in the dialog is displayed.
File Details
This section contains the following read-only information:
File type icon
File name
Folder path
Created by (user)
Date created
Approval Panel
A simplified version of the approval panel (as displayed to the right of the Offer and Interaction Designer toolbar) is displayed below the file details section in the Manage File Approvals dialog. It behaves as its equivalent displayed in those contexts, with the following exceptions:
The Open latest approved version and Open latest version buttons are not displayed.
The View/manage the approval of this file button is not displayed.
In contrast with the approval panel shown at the designer toolbars, if you invoke an approval action (such as requesting a file’s approval) from the dialog’s approval panel, you are not precluded from doing so if outstanding changes are present within the currently displayed version of the file. For example, you cannot initiate approval of an offer containing an unsaved change from the Offer Designer approval panel; however, you can do so from the Manage File Approval dialog (in this case the approval is carried out in respect of the version of the file as shown in the dialog).
Approval Details
This is displayed just below the approval panel and displays a textual summary of the current approval state of the file.
In addition, any comment included with the approval request is displayed. If an approval request is resent and a comment supplied, it is prefixed to the original comment (this can be repeated if necessary)
Approval requirements
This section appears just below the approval synopsis.
Its contents are dependent on the file type’s approval criteria
If Everyone in the user group(s) must approve the file:
‘All approvers must approve this file’
If At least the following number of user(s) must approve:
‘[n] approver(s) must approve this file’
Approvers
This tabset appears at the bottom of the Manage File Approvals dialog.
It consists of three tabs:
Waiting: this tab lists potential approvers who have yet to approve the file
Approved: this tab lists those users who have granted approval of the current file
Denied: this tab lists those users who have denied approval of the current file
Auto-Refresh
The Manage File Approval dialog is auto-refreshed every 10 seconds, meaning that a user who requested a file’s approval can be automatically made aware of a change in its approval status if the file is currently open.
Interaction Designer – File Approval Ramifications
The following sections discuss the ramifications of file approval within the Interaction Designer.
Offer Approval and the Interaction Designer
File approvals are not taken into account when executing offers in Test mode.
However, in Production mode, when executing offers:
If both interaction and offer approval are disabled, approvals are disregarded when executing workflows in Production mode.
If interaction approval is disabled and offer approval enabled, it is not possible to execute an offer activity without an approved version of the offer template with which it is configured.
If an approved offer template version exists:
If the current version is approved, it is used at offer activity execution.
If a previous version is approved (but the current is not), the previous version is used at offer activity execution.
If interaction approval is enabled and offer approval is disabled, it is not possible to execute a workflow unless the interaction within which it exists has been approved. Any offers’ approval statuses are not taken into account.
If both interaction and offer approval are enabled:
It is not possible to execute a workflow unless the interaction within which it exists is approved.
It is not possible to execute an offer without an approved version. If an approved version exists it is used (whether the current version, or a previous version (if the current version is not approved)).
Offer Approval and Interactive Activity Execution
If offer approval is enabled and a long-running interactive activity, which triggers downstream execution of an offer activity, is running, the offer activity will use content based on the most recent approved version (as might be expected).
If the offer activity’s template is updated and approved, on the next occurrence of the offer activity’s execution, the newly approved content will be used. If the offer template is updated but not approved, the older, approved version will continue to be used.
Offer Activity Configuration Panel – Approval Status Icon
Also, within the Interaction Designer, the icon displayed within an offer activity’s configuration panel gives a visual indication as to the approval status of the offer template with which it is configured. Note that this only applies if offer approval has been enabled.
The following summarizes the display of the icon in this context:
Not approved: gray/yellow icon
Awaiting approval: amber icon
Approval denied: red icon
Approved: green icon
Not approved (previous version approved): half green, half grey/yellow icon
Awaiting approval (previous version approved): half green, half amber icon
Approval denied (previous version approved): half green, half red icon.
File Approval Widget
A file approval widget is available at the Dashboard Designer. It provides the ability to customize a dashboard to display lists of files in respect of which a user’s attention is required, either as an approver, or as an approval requester.
Full details of the file approval widget are provided in the Dashboards documentation.
Operations-Approval Summary Tab
An Approval Summary tab is provided within the Operations Interface.
It provides an at-a-glance summary of the current state of files’ approval statuses to operational users.
Full details of the Approval Summary tab are provided in the Operations Interface documentation.
Approval-Auditing
Audit log records are generated when the following approval activities are undertaken:
File Access - Request File Approval
File Access - Cancel File Approval Request
File Access - Resend File Approval Request
File Access - Approve File
File Access - Deny File Approval Request