Read Confirmation User's Guide

Usage of the Read Confirmation Plugin is quite simple. There is only one menu entry to create, edit or view the status of a confirmation request. The target users of a request will be notified of the request on the page itself and only have to click on a link if they are asked to acknowledge the page. A new macro (the "Important Information Macro") is included in the plugin and can be placed on a central page like the dashboard to inform the user of all outstanding confirmation requests.

Creating a read confirmation request

Every user who has been granted the right to use the plugin (see "Configure permissions"), can create a read confirmation request by following these steps:

• Navigate to the page for which a confirmation request should be created
• Open the "..." menu in the top right of Confluence and click on "Read Confirmation".

The confirmation request is specified on a form as seen in the following screenshot:

Description of the fields:

• Search: You can search for target users and groups (see below) by typing the beginning of the user's full name, username or the name of the group. Then select one of the suggested user in the popup.
• Target users: A "target user" is a confluence user who should read the page. Please enter the users as a comma separated list of usernames or use the search field (see above). 
• Target groups: A comma separated list of confluence group names. Each user inside these groups will be considered a "target user". The members of a group are evaluated on demand which means that if you add or remove a user to/from a group after creating a confirmation request the change will be taken into account for future notifications and page displays through the plugin. 
  
  Note: It is required to enter at least one user or a group containing at least one user. If the advanced configuration option "Allow detailed status" has been removed at least two users (specified as user list or group members) must be specified to ensure their anonymity.
• Exclude users: Allow to enter a list of users who should not be targeted even if they are members of one of the target groups. This field will only be available if the advanced configuration option "Allow to exclude users from target groups" is active.

• Deadline (optional): Click inside the field to enter a date in the future using the calendar popup or type it manually (format YYYY-MM-DD). You can erase the date with the read X Icon. The target users who have not read or acknowledged the page by this date will be reminded via email (if notifications are enabled). Confirmation Requests which are still pending after this date will be highlighted in the list of the Important Information Macro.
• ACK required: If this is checked the target users have to explicitly click on a link to acknowledge the page content. The link is displayed above the page content. The status of acknowledgement is tracked separately from the view status. If no acknowledgement is required the target user only have to view the page.
• Show User Details: The creator of the read confirmation request can specify that he wants to see the confirmation status of each user separately by checking this field. The detailed status will only be displayed if the respective advanced configuration option has been activated (see below for screenshots of both alternatives).
• Status on page: Show the confirmation status of all target users directly on the confluence page to the request creator.
• Notification: Notify all target users immediately after saving the confirmation request via email. This feature may be deactivated in the notification configuration of the plugin.
• Comment for target users: Add a comment to the confirmation request that will be shown to all target users. This feature may be deactivated in the advanced configuration of the plugin.
• Feedback via Workbox: The creator of a read confirmation request can choose to be notified via the Confluence Workbox when all target users have read / acknowledged the page, or for each user individually or not at all.
• Feedback via email: The creator of a read confirmation request can choose to be notified via the email when all target users have read / acknowledged the page, or for each user individually or not at all.

After filling the form the "Save" button must be clicked. The "Back to page view" button discards the request.

Viewing the status of a confirmation request

Every user who has the "View Confirmation Status" permission can view the status of a request by clicking on the "Read Confirmation" entry in the "Tools" menu. 

For every target user the following information is displayed (a target user may be explicitly specified with his username or via a membership in one of the target groups):

• Full name of the user.
• View status:  means that the user has viewed the page,  that the request is still pending. If the advanced configuration option "Show confirmation time" has been activated the time (or date) at which the user has viewed the page is displayed after the icon. The confluence page version the user has seen is shown in the next column.
• If "ACK required" is checked the same information (icon, date and version) are shown for the acknowledgement status.
• Reminded: Every user who has been notified of a pending request will be marked as reminded with a 

The following actions are available:

• Refresh: Reloads the confirmation status
• Reset Confirmation Status (requires the "Edit Confirmation Request" permission): Reset all status information of every user to "not viewed" and "not acknowledged".
• Remove Confirmation Status (requires the "Delete Confirmation Request" permission): Deletes the confirmation request and all status information altogether.
• Send reminders now (requires the "Send Reminders" permission): Every target user who has not read or acknowledged the page yet will receive an email reminder.
• Save (requires the "Edit Confirmation Request" permission): Next to the status the details of the read confirmation request are displayed. If the current user has the required permission these details may be changed (e.g. a new deadline or a new target user).
• CSV Link: You can export the list as a CSV file.

Without the "Allow detailed status" advanced configuration option the status is displayed differently:

Only the sum of users that has viewed or acknowledged the page are visible. Users who have not viewed the page will remain anonymous. You can still see the progress of the confirmation request.

Viewing or acknowledging a confirmation request

If another user has requested that you read a confluence page you will see the following green box above the page content (the creator of the request is shown). No action other than reading the page is required.

If the creator has required your acknowledgement of the page the box will be slighty different (see the blue box in the screenshot below). After reading the page you can acknowledge the content by clicking on the link with the text "Please click here when you are done" inside the blue box.

Immediately after clicking the acknowledgement link (or if you revisit the page at a later time) the box changes to a green "Acknowledged" box:

If the page is edited after you have acknowledged a page the following is displayed allowing you to renew your acknowledgement:

When viewing a page for which you have requested a read confirmation request yourself you will see the following. The confirmation status will only be displayed if you have enabled "Status on page" when creating the request. The link in the box ("read confirmations") will get you to the status / edit page (see above).

The Important Information Macro

You will need a central page like the dashboard to display a list of all pending confirmation requests for the user currently logged in. Otherwise it will be very hard for a user to make sure that he has seen all pages with requests. To add the macro just edit a page in confluence and add the "Important Information Macro" with the Confluence macro browser:

The following parameters are available:

• Days in future: Shows all requests which have a deadline ending within the given days. 
• Days in past: Shows all confirmation requests with a deadline (or a modification date for requests without a deadline) which is at most the given days in the past. 
• Status filter: Defines which confirmation requests to display. 
  • all: All Requests in the date range will be shown regardless of their status.
  • pending: Displays confirmation requests that are still pending. 
  • pending or updated: Displays confirmation requests that are still pending or where the page has been updated since the user viewed or acknowledged them.
  • done:Displays confirmation requests that are done (viewed and acknowledged if required). 
  • none: Displays no confirmation requests for the current user. This only makes sense when enabling "Include my requests".
• Deadline filter: Only displays confirmation requests which have a deadline. 
• Include my requests: Include confirmation requests in the list that has been created by the current user.
• List length: Maximal number of items to display. The list is sorted by the modification date of a request. If there are more requests than specified here only the first n request will be displayed.

The Important Information Macro renderes the following list:

These information are displayed to the user:

• Title (Space): The page title and confluence space of the page with a confirmation request. The page title is a link to the page.
• Requested by: The full name of the confluence user who created the confirmation request. If "include my requests" is checked in the macro configuration the text "requested by me" is shown for these requests.
• Request Date: The date (or time) at which the confirmation request was created.
• Deadline: The date by which the page should be read. If the deadline has expired the cell will be highlighted.
• Status:  means that you already has viewed (and acknowledged, if required) this page.  is displayed for pending requests. A yellow exclamation point  means that the page has been updated since you viewed / acknowledged the page.
• CSV Link: You can export the list as a CSV file.