Difference between revisions of "Field Revision Annotations"

Revision as of 13:35, 14 June 2019

Overview

Annotations is a feature that allows users to add or view annotations at the individual field level (ex: Standard Fields such as name or address, and also Custom Fields). These edits to specific fields can be made while keeping the rest of the record locked. 

Flexible role-based security allows the System Administrator to configure UTA role-based permissions: different users will have the ability to view or add annotations to fields, while others the ability to edit that field value. 

Our annotations feature offers you, the SmartSimple user, an additional communications vehicle for both internal and external users. While annotations are similar to the [wiki/Notes Notes] feature, it is targeted towards individual fields. For example: If one of your grants administrators is reviewing an application, and notices that a particular field needs to be revised by the applicant - the administrator can then highlight this field with an annotation and send a comment to the applicant concerning which edit to make. The applicant can review the comment and make the appropriate change. 

Configuration - Essentials

In order to configure Field Revision Annotations for your SmartSimple instance, you must create an Annotation Type and permission it based on roles. 

Following this, you then have the ability to go into a Universal Tracking Application and configure UTA Role-based permissions against individual UTA statuses to control who can view and edit the annotations, and who is able to modify the fields in annotation mode. 

Creating an Annotation Type

The Annotation Type is necessary to use the Field Revision Annotation feature; it allows users to define role-based permissions to control who can use that specific type of annotation.

1. Click the 9-square menu icon on the top right of your page. 

2. Under the heading Configuration, select Global Settings.

3. In the first tab of Global Settings (labelled System), select Annotation Types. 

• This will open up the list of available Annotation Types in the system. If you do not have any already configured in your system, the page will be blank. 
• To edit an existing Annotation Type, simply click the pencil icon on the left of the annotation name. 

4. Click the + button on the top left to create a new Annotation Type. 

5. Provide an appropriate name, caption and description for your new Annotation Type.

• The Name and Caption field are normally labelled the same, if not similarly. 
• The Description field is important to fill out for the configuration and creation of all SmartSimple features: it is best practice to provide guidance in case anyone else needs to modify or use your configuration 
• The Display Order field determines where on the page a user will see your Annotation Type listed. The Display Order works from lowest to highest number - ex: inserting 1 into the field will ensure that your type is listed first, and any type with a display order greater than 1 will be listed afterwards in ascending order. If nothing is inputted the system defaults to a display order beginning at 100 and rising in increments of 100 for subsequent fields.
• The Colour field allows you to choose which colour your annotations will appear when they are written with this type. 

6. When you have filled out all the fields to create a new Annotation Type, click Save. 

Setting Permissions and Availability

After completing the steps to creating a new Annotation Type, this will bring you to the Edit page for that type. 

1. Select the second tab on the Annotation Type editing page, labelled Permissions and Availability.

 

• View & Create - Click into the text box to select which roles will have the ability to both view and create this Annotation Type. The default will be Everyone. If you have a role-specific annotation - for example, a Reviewer Annotation Type, then you should only select the roles that need access to this type, such as those with the role Reviewer assigned. 
• View Only - Click into the text box to select which roles will have the ability to view this Annotation Type. The default will be Everyone. A role-specific annotation type, such as those for Reviewers, might only require specific roles to see but not create this annotation type, such as Employee or Applicant. 

2. After selecting the appropriate roles to access your Annotation Type, click Save.

Setting Statuses for UTA-based Annotation Types

After building your Annotation Type, go to the UTA that you want this annotation to be available for. For example, a Reviewer Annotation Type that is written by a reviewer to be seen by an applicant is appropriately associated with a Grants Manager application. In this series of steps, we will select the Status that will allow the Annotation Type to be used by the roles that have been assigned. 

1. To find your UTA, click the 9-square menu icon on the top right of the page.

2. Under the heading Applications, select the desired application to open up its details. 

3. Click the gear icon on the top of the page to go into Configuration Mode. 

4. Go to the second tab of the Configuration Settings - this displays the settings associated with the Level 1 Entity of the application.

 The nomenclature for your application and configuration tabs will differ depending on your SmartSimple instance. 

5. Select Statuses under the heading General Settings. 

A list of statuses associated with the Level 1 Entity of your UTA will appear. 

6. Select the status that you want to add this Annotation Type to. 

• If the status you would like to add an Annotation Type is not yet created, learn how to create a status. 

  

In this example, the Under Review status is appropriate for an Annotation Type that pertains to a Reviewer. 

The details of the status will open. 

7. Click the second tab of the Status page, titled Permissions & Availability. 

8. Once you are done permissioning the annotation feature on a specific UTA status, click Save. 

Enabling Annotation Permissions

Now you need to enable annotation permissions on the newly created Annotation Type.

1. Click the 9-square menu icon on the top right of your page.

2. Under Configuration, select Global Settings.

3. Click Annotation Permissions, which is available on the first tab. 

Two tabs will appear: the first for Global Permissions and the second for Status Specific Permissions. Enabling permissions for your Annotation Type can be successfully configured from both tabs. Since you have a status-specific Annotation Type - a Reviewer Type for the status Under Review - the Status Specific Permissions tab is applicable.

• Entity Type: Select the entity that your status and Annotation Type falls under. In this case, it is a specific UTA and the Level 1 Entity that we configured our Annotation Type for. 
• Status: Select the status that your Annotation Type applies to. In this case, it is the Under Review status. 
• Set System Role and Association Role permissions, as applicable and necessary. 

4. Click Save. 

Using Annotation Types

After an Annotation Type has been created, configured onto a UTA Entity and Status, and role-based permissions were enabled on the status and in Global Settings, you can double-check that your annotation works by going to the UTA you want to use the annotation for.

1. Click the 9-square menu icon on the top right of your page.

2. Under the Applications heading, select the appropriate application. 

3. Select the Level 1 Entity that has the appropriate status the Annotation Type is configured for.

In this example, it must be one that has Status - Under Review. 

4. Select the Annotations feature, which appear on the left-side menu of the Level 1 Entity page. 

5. A list of annotations will appear. If there are no annotations yet, the page will be blank. To create a new annotation, click the pencil icon on the right hand side of the page. 

When you are in Annotation Mode, all of the fields can now be clicked into and annotations can be created and viewed based on which roles you have permissioned.

Clicking into a field will open up a window with a pencil icon that you can click to create a new annotation.

[[File:New annotation.png|

Under Annotation Type, select the type that you have created to ensure that the correct and appropriate roles will have access to this annotation.

After filling in the content of your annotation, click Save. Any viewer with a role that is permissioned to Edit Fields will be able to view and edit the field that you have written an annotation for. 

Using Field Annotations

To use Annotation a user must first switch on this functionality against the individual record.

Once Annotation has been switched on the user can add, edit or view the annotations, depending on the Status based permissions.

The user may also be able to edit the actual field value when it is locked, depending on the Status based permissions.

Switch on Annotation

If you have do not have the Open Record in Annotation Mode permissions but have View or View and Create permission, then when you first access the record you will see a Turn On Annotation button along the top of the screen.

If you click on this button, or if you have Open Record in Annotation Mode permissions, then you will automatically access the record with annotation switched on. The Turn Off Annotation button will be displayed along the top of the screen.

Add, Edit or View the Annotation

If the user has View Annotation or View and Create Annotation permissions, then they would automatically see the Annotations tab along the right hand side of the screen. If they clicked on this then it would expand to show any Annotations created.

The Standard or Custom field that the Annotation exists against appears at the top of the individual Annotation within the overall Annotation tab, while the message, the person who entered the message and the date it was entered also appears.

Turning on Annotation also exposes a series of Edit, View or Modify options against individual Standard and Custom fields, as well as highlighting those fields with existing annotations.

View Annotations

If the user has View but not View and Create Annotation permissions then they will not be able to access the New Annotation or Reply buttons against individual fields.

They would still automatically see the Annotations tab along the right hand side of the screen.

If they clicked on this then it would expand to show any Annotations created.

If the user then clicks on one of the Annotations listed then the Annotation is exposed against the relevant field, but still with no Reply or Modify option.

Edit Field

The Edit fields Annotation functionality is only relevant when the record is locked on status and the user has View Annotation Roles set.

If the user has Edit Field in Annotation Mode Roles but does not have the View and Create Annotation permissions then, when they click on a field caption which has no previous annotations, they will see a pop-up informing them that there is "No annotation found on this field".

If the user has Edit Field in Annotation Mode Roles but does not have the View and Create Annotation permissions then, when they click on a field caption with previous annotations, they will see a pop-up with a Modify button. If they click on the Modify button then they are presented with the Edit Field screen, but the ability to edit the individual field is controlled by the associated Field Permissions.

If the user has both Edit Field in Annotation Mode Roles and View and Create Annotation permissions then, when they click on a field caption which has no previous annotations, they would see a small icon with the caption New Annotations.

If the user has both Edit Field in Annotation Mode Roles and View and Create Annotation permissions then, when they click on a field caption which has already annotations, they would see a small icon with the caption Reply/Modify and the historic annotations displayed.

If the user clicks on the New Annotations or Reply/Modify button then they will see a Field Value option in the New Annotation screen.

If they edit the Field Value and click Save then the value stored against the field will be updated accordingly.

Review History

The Revision History feature will list the full annotation history in one place. The history is updated each time when changes are submitted through the Annotation submit button. The record must be under Status Lock in order for the Annotation Submit button to appear on the page.

The history will show both when the field is edited and when the record is submitted.

The ability to access the Revision History section is controlled by the UTA Security Settings.

The Revision History section is available by clicking on the Options section at the top of the UTA record, then clicking on the resulting Revision History section.