Overview

Annotations serve as a collaborative tool that allows users to append notes and responses directly to specific fields within a record. By utilizing field-level annotations, users can modify particular fields and respond to comments without impacting the remainder of the record. This article will provide guidance on how to utilize and configure the annotation collaboration feature as part of the application review process.

Note:

You must possess the role of Global Administrator to configure this feature.
The interface and recommended configuration practices for the annotations feature have been updated as part of the July 2024 upgrade.
The annotations feature permits editing of only a single field at a time. Validation will be executed solely on the field being modified. Consequently, if dynamic field visibility controls are being utilized or if full validation of the entire form is required, it may be necessary to exit annotation mode and revert to an unlocked status to accomplish this.

Functionality of Annotations

This section will outline the configuration of the annotation feature within an application process involving an applicant, a program manager, and a reviewer.

1. Applicant Submits Application

The applicant inputs the requisite information into a form and submits it.

2. Program Manager Assigns a Reviewer

The program manager designates a reviewer for the application and progresses the application to the subsequent stage.

3. Reviewer Conducts Initial Review and Creates Annotations

The reviewer receives notification of their assignment to review the application. In this instance, the application is not yet ready for approval or rejection, prompting the reviewer to make field-level suggestions (annotations) for modifications or clarifications. The reviewer hovers over and left-clicks the desired field to access a new annotation window. Here, they input a message requesting the applicant to amend or clarify something pertinent to this field, and subsequently save the annotation.

Left-click the desired field to create a new annotation. Enter the relevant content into the Message field and click Save.

This procedure is repeated for all fields necessitating modifications or clarifications. Upon completion of all annotations, the reviewer clicks the annotation submission button to return the record to the applicant.

Annotations will be displayed in the right-hand panel. Click the annotation submission button to return the record to the applicant.

4. Applicant Reviews Annotations, Modifies Values, and Adds Clarifications

The applicant is notified that action is required regarding their application. The applicant navigates to their application, which opens in Annotation Mode. In Annotation Mode, fields without annotations are locked. The applicant can view a list of annotations in the right panel and may click on any annotation to engage in a specific field-level discussion.

A list of annotations appears in a right-hand panel.

When focused on an annotation, the applicant can click the Reply button to open a modal window, where they can modify the field value and add a clarifying message.

Click on a specific annotation thread to expand it. Click the Reply button to respond to the annotation.

Annotations from other users (such as the reviewer) are highlighted in yellow, indicating they may require a response, while annotations created by the applicant are highlighted in blue.

Your own annotations appear in blue while annotations made by other users appear in yellow.

After responding and modifying field values, the applicant clicks the annotation submission button to advance the status, triggering a workflow that notifies the reviewer of the changes made.

5. Reviewer Conducts a Subsequent Review and Marks Annotations as Resolved

The reviewer is notified that action is required and proceeds to the application. The reviewer assesses the changes and the applicant's responses. If no further modifications or clarifications are necessary, the reviewer marks each field-level annotation as resolved.

Click the Mark as Resolved button to close an annotation thread.

Resolved annotations are denoted with a green check mark, indicating that no further action is required.

Resolved annotations appear at the bottom of the annotation list, marked with green coloring and a checkmark.

If all outstanding changes are addressed, the reviewer advances the application using the annotation submission button.

6. Exiting Annotation Mode

Users may exit Annotation Mode by clicking the close icon (“X”) in the gray box. This action may be necessary to access the left navigation or other record-related elements that are not visible in Annotation Mode.

Note: Fields found under the "More" tab of the left navigation do not support annotations.

Click the close icon to exit Annotation Mode.

To re-enter Annotation Mode, click the Annotation Mode toggle located in the high visibility area at the top right of the record.

To re-enter or toggle on Annotation Mode, click the icon in the high visibility bar.

Configuration

The following provides a detailed explanation on how a Global Administrator may configure the annotations feature in accordance with the scenario outlined above.

User Roles

It is necessary to establish two roles: one for the applicant and another for the individual responsible for the review process. Depending on your organizational procedures, you may already possess two applicable roles, or you may opt to create two new roles. If you choose to create new roles, these can be designated as system roles or UTA (association) roles based on your operational requirements. To create new roles, please navigate to the Menu Icon > Roles and Security > User Roles > and click the New Role button (indicated by a plus sign). Typically, the roles created would be labeled as “Applicant” and “Reviewer” or “Internal Staff”.

Annotation Types

Annotation types define the individuals authorized to make annotations and the circumstances under which they may do so. Generally, there are two types of annotations: one designated for the applicant and another intended for an internal staff member or designated reviewer.

Creating a "Reviewer" Annotation Type

Navigate to Menu Icon > Global Settings > System tab > Annotation Types.
Click the New Type button (represented by a plus sign).
Establish an annotation type with the name and caption of either “Reviewer Annotation” or “Staff Annotation,” depending on your operational terminology.
Provide a description outlining the purpose of this annotation type. For instance, you may enter “Used to create field-level annotations by reviewers requesting changes from the applicant.”
Proceed to the Permissions & Availability tab.
In the Allow View field, select both the applicant and reviewer roles. This ensures that both applicants and reviewers can view both types of annotations on a record.
In the Allow Create field, select only the reviewer role, thereby restricting the creation of the "Reviewer" type of annotation to reviewers exclusively.

Create an "Applicant" Annotation Type

Navigate to Menu Icon > Global Settings > System tab > Annotation Types.
Click the New Type button (indicated by a plus sign).
Establish a type with the name and caption of “Applicant Annotation.”
Provide a description that outlines the purpose of this annotation type. For example, you may enter “Used to create field-level annotations by the applicant, responding to change requests from a reviewer.”
Proceed to the Permissions & Availability tab.
In the Allow View field, select both the applicant and reviewer roles. This ensures that both applicants and reviewers can view both types of annotations on a record.
In the Allow Create field, select only the applicant role. This restricts the creation of the applicant type of annotation to applicants exclusively.

Setting up Statuses for Annotations

Statuses are utilized to manage actions at various stages of a process, such as directing the user directly into annotation mode and notifying a user of required changes to their application. To realize the aforementioned scenario, multiple statuses are employed within our intended universal tracking application.

Statuses can be created by navigating to the desired Universal Tracking Application > Configuration Settings > selecting the appropriate tab (such as “Level 1 Grant”) > Statuses > clicking the New Status button (indicated by a plus sign). Enter the requisite information and define the availability and permissions, then click Save.

Below is an explanation of each status and its configuration:

Name	Description	Configuration Steps
Draft	The grant application is currently being completed by the applicant.	Activate Is Default Status Activate Is Default Copy Status Navigate to the Permissions & Availability tab and, within the “Availability” section, select the pertinent grant types for the Enable on Grant Types field.
Submitted	The applicant has submitted the application and can no longer make edits.	Activate Lock On Status Navigate to the Permissions & Availability tab and, under the “Role Permissions” section, select the “Program Manager” user role for the Override Lock field to enable progression of the record after assigning a reviewer. Navigate to the Permissions & Availability tab and, under the “Availability” section, select the relevant grant types for the Enable on Grant Types field.
Reviewer Assigned and Notified	The reviewer has been informed that the application is ready for evaluation.	Activate Lock On Status Navigate to the Permissions & Availability tab and, under the “Role Permissions” section, select the “Program Manager” user role for the Override Lock field to facilitate record progression. Navigate to the Permissions & Availability tab and, under the “Availability” section, select the relevant grant types for the Enable on Grant Types field. Establish a Level 1 workflow to send an email notification to the reviewer by navigating to Menu Icon > Workflows > Create a new workflow > Set Workflow Object to this UTA and set Trigger On to this status.
Reviewer Annotation and Creation	The reviewer adds annotations to the grant application, requesting modifications and clarifications. They also examine the annotations provided by the applicant.	Activate Lock On Status Navigate to the Permissions & Availability tab and, under the “Annotation System Role Permissions” section, select the “Applicant” user role for the View field, select the “Reviewer” user role for the View and Create field, select the "Reviewer" user role for the Mark as Resolved field, and select both “Applicant” and “Reviewer” user roles for the Open in Annotation Mode field. Navigate to the Permissions & Availability tab and, under the “Availability” section, select the pertinent grant types for the Enable on Grant Types field.
Revisions Requested	The applicant is notified and is required to modify values, respond to annotations, and provide clarity regarding the issues raised.	Activate Lock On Status Navigate to the Permissions & Availability tab and, under the “Annotation System Role Permissions” section, select the “Applicant” user role for the View field as well as the Edit Field input, select the “Reviewer” user role for the View and Create field, and select both “Applicant” and “Reviewer” user roles for the Open in Annotation Mode field. Navigate to the Permissions & Availability tab and, under the “Availability” section, select the pertinent grant types for the Enable on Grant Types field. Establish a Level 1 workflow to send an email notification to the applicant by navigating to Menu Icon > Workflows > Create a new workflow > Set Workflow Object to this UTA and set Trigger On to this status.
Applicant Revisions Submitted	The reviewer is notified that the applicant has implemented the requested changes and provided clarity.	Activate Lock On Status Navigate to the Permissions & Availability tab and, under the “Annotation System Role Permissions” section, select the “Applicant” and “Reviewer” user roles for the View field, select the “Reviewer” user role for the View and Create field, and select both “Applicant” and “Reviewer” user roles for the Open in Annotation Mode field. Navigate to the Permissions & Availability tab and, under the “Availability” section, select the pertinent grant types for the Enable on Grant Types field. Establish a Level 1 workflow to send an email notification to the reviewer by navigating to Menu Icon > Workflows > Create a new workflow > Set Workflow Object to this UTA and set Trigger On to this status.
Approved	The grant application has received approval.	Activate Lock On Status Navigate to the Permissions & Availability tab and, under the “Availability” section, select the pertinent grant types for the Enable on Grant Types field.
Declined	The grant application has been declined.	Activate Lock On Status Navigate to the Permissions & Availability tab and, under the “Availability” section, select the pertinent grant types for the Enable on Grant Types field.

Explanation of Status Settings

These settings can be located at UTA > Configuration Settings > Level 1 tab > Statuses > Select a Status.

Lock On Status

This feature prevents users from modifying the application record and conceals any configured Save and Submit Buttons associated with this status.

Override Lock

This functionality permits a user role to edit a locked record and access the submit and save buttons configured for this status.

Availability

This setting determines which types of applications will have access to this status.

Annotation System Role and Annotation Association Role Permissions

Depending on business requirements, you may opt to utilize Annotation System Roles (e.g., any individual with the system reviewer role possesses permissions) or Annotation Association Role Permissions (e.g., any individual associated with the record as a contact in the UTA role of reviewer has permissions).

View

Identifies who is permitted to view the annotations.

View and Create

Identifies who is authorized to create new annotation threads and respond to existing annotations.

Edit Field

Identifies who is allowed to modify the value of the field being annotated and respond to existing annotation threads.

Mark as Resolved

This setting controls who can access the "Mark as Resolved" and "Mark as Unresolved" buttons, which are typically available to users assigned the role of reviewing the application.

Open in Annotation Mode

Identifies who can view the record in annotation mode by default.

Anonymize Creator

This feature conceals the identity of the individual who added the annotation.

Workflow Notifications

At various stages throughout the process, notifications will be automatically dispatched to the reviewer and applicant, indicating that action is required on an application.

To implement this, a workflow can be established by navigating to Menu Icon > Workflows.

Click the “New Workflow” button (indicated by a plus sign).
Select the desired UTA for the Workflow Object field.
Select the appropriate Level 1 status for the Trigger On field, then click Save.
Configure a task with a Task Type of “Acknowledgement” and select the message type as “Email”.
In the email message, it is advisable to include both the name of the application and a link to the application.

Submit Buttons and Annotation Submission Buttons

Submit buttons facilitate the movement of a record between statuses that are not locked. A user role may also be granted permission to override a locked status to access submit buttons.

Annotation submission buttons are designated for use exclusively in Annotation Mode when the record is locked, during which other submit and save buttons are concealed.

Both categories of submission buttons can be configured by navigating to the desired UTA > Configuration Settings > Click on the desired Level 1, 2, or 3 tab > Submit and Save Buttons.

The following submit buttons have been created for our scenario:

Name	Description	Type	Configuration Steps
Submit	This action allows the applicant to submit their application, thereby locking it to the applicant.	Submit	Select “Draft” in the Available to Status field. Select “Submitted” in the Submit to Status field. Enable Confirmation Alert Message. In the Confirmation Message input, enter: “Your application will be sent for review. Once sent, you will no longer be able to modify your application. Are you sure you wish to continue?” Enable Confirmation Page. For Title, enter “Application Submitted”. In the Message input, enter: “Thank you. Your application has been submitted and will be reviewed.” For the Redirect URL, click the URL Lookup button (represented by the binoculars icon) to select the page to which the user should be redirected after submitting their application. In the Button Caption input, enter “Back to list of applications”.
Begin Review Process	A reviewer is assigned to approve, decline, or annotate the application.	Submit	Select “Submitted” in the Available to Status field. Select “Reviewer Assigned and Notified” in the Submit to Status field. Navigate to the Permissions & Availability tab and, in the “Role - Permissions” section, select the “Program Manager” user role for the Allow View field.
Move to Reviewer Annotation and Review	The record is transitioned to reviewer annotation and review after the reviewer has been assigned and notified.	Submit	Select “Reviewer Assigned and Notified” in the Submit to Status field. Navigate to the Permissions & Availability tab and, in the “Role - Permissions” section, select the “Program Manager” user role for the Allow View field.
Send Requested Revisions to Applicant	This action sends requested revisions to the applicant.	Submit Annotation	Select “Reviewer Annotation and Review” in the Available to Status field. Select “Revisions Requested” in the Submit to Status field. Enable Confirmation Alert Message. In the Confirmation Message input, enter: “Annotations will be sent to the applicant for review and amendment. Once sent, you will no longer be able to add additional annotations. Are you sure you wish to continue?” Navigate to the Permissions & Availability tab and, in the “Role - Permissions” section, select the “Reviewer” user role for the Allow View field.
Submit Revisions	This action sends revisions from the applicant to the reviewer.	Submit Annotation	Select “Revisions Requested” in the Available to Status field. Select “Reviewer annotation and review” in the Submit to Status field. Enable Confirmation Alert Message. In the Confirmation Message input, enter: “Your annotations and amendments will be sent for review. Once sent, you will no longer be able to add additional annotations or make changes. Are you sure you wish to continue?” Enable Confirmation Page. For Title, enter “Revisions Submitted”. In the Message input, enter: “Your revisions have been submitted and will be reviewed.” For the Redirect URL, click the URL Lookup button (represented by the binoculars icon) to select the page to which the user should be redirected after submitting their application. In the Button Caption input, enter “Back to list of applications”. Navigate to the Permissions & Availability tab and, in the “Role - Permissions” section, select the “Applicant” user role for the Allow View field.
Approve Application	The reviewer approves the application, indicating that no further changes are required.	Submit Annotation	Select “Reviewer Annotation and Review” in the Available to Status field. Select “Approved” in the Submit to Status field. Enable Confirmation Alert Message. In the Confirmation Message input, enter: “This record will be moved to approved. Once approved, you will no longer be able to add additional annotations or request changes. Are you sure you wish to continue?” Enable Confirmation Page. For Title, enter “Application Approved”. In the Message input, enter: “The application has been approved.” For the Redirect URL, click the URL Lookup button (represented by the binoculars icon) to select the page to which the user should be redirected after submitting their application. In the Button Caption input, enter “Back to list of applications”. Navigate to the Permissions & Availability tab and, in the “Role - Permissions” section, select the “Reviewer” user role for the Allow View field.
Decline Application	The reviewer declines the application.	Submit Annotation	Select “Reviewer Annotation and Review” in the Available to Status field. Select “Declined” in the Submit to Status field. Enable Confirmation Alert Message. In the Confirmation Message input, enter: “This record will be moved to Declined. Once declined, you will no longer be able to add annotations or request changes. Are you sure you wish to continue?” Enable Confirmation Page. For Title, enter “Application Declined”. In the Message input, enter: “This record will be moved to Declined. Once declined, you will no longer be able to add annotations or request changes. Are you sure you wish to continue?” For the Redirect URL, click the URL Lookup button (represented by the binoculars icon) to select the page to which the user should be redirected after submitting their application. In the Button Caption input, enter “Back to list of applications”. Navigate to the Permissions & Availability tab and, in the “Role - Permissions” section, select the “Reviewer” user role for the Allow View field.

Field Revision Annotations