==Feature 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.
Revision Annotations is a feature that Flexible [[Role Based Security|role-based security]] allows the [[Global User Administrator|System Administrator]] to configure [[UTA role]]-based permissions: different users will have the ability to view or add or view annotations at the field level and allow edits to be made to specific fields , while keeping others the rest of the record lockedability to edit that field value.
Flexible Status based security allows Our annotations feature offers you to configure , the SmartSimple user, an additional communications vehicle for both [[Internal|internal]] and [[UTA roleExternal|external]]-based permissions to allow different [[User|users the ability to view or add ]]. While annotations are similar to the [[Notes]] feature, it is targeted towards individual fields while others . For example: If one of your grants administrators is reviewing an application, and notices that a particular field needs to be revised by the ability 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 field valuecomment 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 [[User Role|roles]].
==Configuring Field Revision Annotations== The first step in configuring Following this, you then have the Field Revision Annotation is ability to create an Annotation Type and permission it based on Roles. You can then go to into a UTA [[Universal Tracking Application]] and configure [[UTA role|UTA Role]] -based permissions against individual UTA Statuses [[Status|statuses]] to control who can view and edit the annotations, and who can 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.
To use the Field Revision Annotation feature an Annotation Type needs to be created. The Annotation Type also allows users to define role based permissions to control who can use the specific type1. * Click on the '''Configuration''' 9-square menu, then select the '''[[Roles & Permissions]]''' option and then click icon on the '''Annotation Permissions''' link within the [[Manager Permissions]] section. * The '''Annotation Type''' top right of your page is displayed.* To edit an existing Annotation Type click on the Annotation Type line on the left panel. * To create a new Annotation Type complete the role based permissions listed under the '''New Annotation Type''' section, including the Role Permission settings: ::* View & Create: define those roles that can both view and create this Annotation type::* View only: define those roles that are only able to view this Annotation type * Click '''Save'''. ===Configure Role based permissions against individual UTA Statuses=== Edit the individual UTA Statuses to control who can view and edit the annotations, and who can modify fields in annotation mode. * From the related UTA, click on the '''Settings''' icon.* Navigate to Level 1, 2, or 3 tab, and click on the '''Statuses''' hyperlink.* Create a new status (click on the '''+ New Status''' icon) or edit an existing status (click on the edit status icon).* Go to Permissions & Availability section.* The following fields are related to Revision Annotations:::* '''View Annotation Role''' - those [[UTA role|UTA Roles]] that can view annotations at the particular status::* '''View and Create Annotation Roles''' - those [[UTA role|UTA Roles]] that can view and edit annotations at the particular status::* '''Edit Field in Annotation Mode Roles''' - those [[UTA role|UTA Roles]] that can edit the actual field value when it is locked ::* '''Open Record in Annotation Mode''' - those [[UTA role|UTA Roles]] that will be able to access the entity in Annotation Mode, without the need to explicitly turn annotation on
==Using Field Annotations==:: {{Icon-Menu}} 2. Under the heading '''Configuration, '''select '''Global Settings.'''
To use 3. In the first tab of Global Settings (labelled '''System'''), select '''Annotation a user must first switch on this functionality against the individual recordTypes. '''
Once :: [[File:Annotation has been switched on types.png|500px|border]]: :* This will open up the list of available Annotation Types in the user can addsystem. If you do not have any already configured in your system, the page will be blank. :* To edit or view an existing Annotation Type, simply click the '''pencil icon '''on the left of the annotation name. 4. Click the annotations, depending '''+ '''button on the Status based permissionstop left to create a new Annotation Type.
The user may also be able to edit the actual field value when it is locked5. Provide an appropriate name, depending on the Status based permissionscaption and description for your new Annotation Type.
::: [[File:New annotation type.png|650px|border]]
::
::* 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. '''
===Switch on AnnotationSetting Permissions and Availability===After completing the steps to creating a new Annotation Type, this will bring you to the '''Edit '''page for that type.
If you have do not have 1. Select the second tab on the Annotation Type editing page, labelled '''Open Record in Annotation ModePermissions and Availability.''' 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.
:::: [[ImageFile:TurnOnAnnotationAnnotation type permissions.png|650px|border]] :: ::* '''View & Create - '''Click into the text box to select which [[User Role|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.
If you click on this button, or if you have :::: {{Icon-Menu}} 2. Under the heading '''Open Record in Annotation ModeApplications, ''' permissions, then you will automatically access the record with annotation switched on. The Turn Off Annotation button will be displayed along the top of select the screendesired application to open up its details.
[[Image:TurnOffAnnotation3.png|border]]Click the '''gear icon '''on the top of the page to go into '''Configuration Mode. '''
:::: [[File:Config settings.png|200px|border]]
4. Go to the second tab of the Configuration Settings - this displays the settings associated with the [[Level 1 Entity]] of the application.
<pre> The nomenclature for your application and configuration tabs will differ depending on your SmartSimple instance. </pre>
===Add, Edit or View 5. Select '''Statuses '''under the Annotation===heading '''General Settings. '''
If the user has View Annotation or View and Create Annotation permissions, then they would automatically see the Annotations tab along :::: [[File:Statuses config.png|500px|border]] A list of statuses associated with the right hand side Level 1 Entity of the screen. If they clicked on this then it would expand to show any Annotations createdyour UTA will appear.
The Standard or Custom field 6. Select the status that the Annotation exists against appears at the top of the individual Annotation within the overall you want to add this Annotation tab, while the message, the person who entered the message and the date it was entered also appearsType to.
::* If the status you would like to add an Annotation Type is not yet created, learn [[Status#Creating UTA Statuses|how to create a status]]. ::*: [[ImageFile:AnnotationTabUnder review status.png|300px|border]]
In this example, the '''Under Review '''status is appropriate for an Annotation Type that pertains to a '''Reviewer. '''
Turning on Annotation also exposes a series The details of Edit, View or Modify options against individual Standard and Custom fields, as well as highlighting those fields with existing annotationsthe status will open.
[[Image:AnnotatedFields7.png|800px|border]]Click the second tab of the Status page, titled '''Permissions & Availability. '''
:::: [[File:Annotation for status.png|600px|border]]
{| class="wikitable"
|-
||'''Annotation System Role Permission'''
||
'''View: '''Who is allowed to view the annotations associated with this status
'''View and Create: '''Who is allowed to both view and create annotations on this status
====Add and '''Edit Annotations====Field: '''Who is allowed to edit specific fields that have annotations on them in this status
If the user has View and Create Annotation permissions then, when they first click on a field caption which has no previous annotations, they would see a small icon with the caption '''New AnnotationAnonymize Creator: '''.Choose which roles you would like to hide the identity of when they create annotations on this status
[[Image|-||'''Annotation Association Role Permissions'''||'''View:NewAnnotationButtons.png|border]] '''Which roles will be ''associated ''to view the annotations with this status
'''View and Create: '''Which associated roles will be able to both view and create annotations on this status
If the user has 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 '''ReplyEdit Field: ''' and the historic Which associated roles will be able to edit specific fields that have annotations displayed.on them in this status
[[Image'''Anonymize Creator:AnnotationReplyButtons.png|border]] '''Choose which associated roles you would like to hide the identity of when they create annotations on this status
::* Good examples of associated roles might be users with '''Contractor '''roles, or a '''Grant Writer '''who is working on multiple grants at the same time, etc
If they click |}8. Once you are done permissioning the annotation feature on this a specific UTA status, click '''New Annotation'Save. '' or '''Reply''' button then they should be presented with the New Annotation screen.
[[Image:NewAnnotationScreen===Enabling Annotation Permissions===Now you need to enable annotation permissions on the newly created Annotation Type.png|900px|border]]
1. Click the 9-square menu icon on the top right of your page.
They can select the Annotation Type:::: {{Icon-Menu}} 2. Under '''Configuration, with the list of available Annotation Types controlled by the Role Permission settings for the individual types '''select '''Global Settings. '''
They can also enter text in 3. Click '''Annotation Permissions, '''which is available on the Message field and click Savefirst tab.
The Two tabs will appear: the first for '''Global Permissions '''and the second for '''Status Specific Permissions. '''Enabling permissions for your Annotation would then Type can be visible within the successfully configured from both tabs. Since you have a status-specific Annotation tab on Type - a '''Reviewer Type '''for the right hand side of status '''Under Review '''- the screen, the corresponding field would be highlighted if Annotation Status Specific Permissions tab is turned on and the annotations visible by clicking on the field captionapplicable.
:::: [[File:Status specific annotation permission.png|400px|border]]
:::
:::* '''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. '''
====View Annotations=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.
If 1. Click the user has View but not View and Create Annotation permissions then they will not be able to access 9-square menu icon on the '''New Annotation''' or '''Reply''' buttons against individual fieldstop right of your page.
They would still automatically see the Annotations tab along the right hand side of ::::: {{Icon-Menu}}2. Under the '''Applications '''heading, select the screenappropriate application.
If they clicked on this then it would expand to show any Annotations created3. Select the Level 1 Entity that has the appropriate status the Annotation Type is configured for.
If the user then clicks on In this example, it must be one of the Annotations listed then the Annotation is exposed against the relevant field, but still with no Reply or Modify optionthat has '''Status - Under Review. '''
[[Image:AnnotationViewOnlyScreen4.png|border]]Select the '''Annotations '''feature, which appears on the left-side menu of the Level 1 Entity page.
::::: [[File:Annotations side bar.png|150px|border]]
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.
::::: [[File:Annotation mode.png|150px|border]]
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|border]]::::: [[File:Annotation fill in window.png|850px|border]]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.====Edit Using Field Annotations====If the user has '''View Annotation '''or '''View and Create Annotation '''permissions, they would automatically see the '''Annotations '''tab along the left hand side of the screen.
The Edit fields Annotation functionality is only relevant when the record is :: [[Status LockFile:Annotations left hand menu.png|170px|locked on statusborder]] and If they clicked on this tab, it would open up any of the user has '''View Annotation Roles''' setAnnotations that have been created on this record.
If :: [[File:Annotations examples.png|1000px|border]] The [[Standard Fields|standard]] or [[Custom Fields|custom field]] that the user has Edit Field Annotations exists against will appear at the top of each individual Annotation - in Annotation Mode Roles but does not have the View example above, these fields are '''Branch '''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"'''Supporting Sponsorship Document. '''
The '''Annotation Type '''and the annotation content will appear right below the field title.
If On 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 bottom right will see a pop-up with a Modify button. If they click on be the Modify button then they are presented with creator of the Edit Field screen, but annotation and the ability to edit the individual field is controlled by the associated [[Field Permissions]]time and date stamp that it was created.
===Editing or Replying to Annotations===If the user has both has '''Edit Field in Annotation Mode Roles and ''' ''and '''''View and Create Annotation Annotations'''''' '''permissions then, when they click open up a record on a they will be able to view which field caption which has no previous annotationsan annotation highlighted against it, and they would see a small icon with will have the ability to click into the field directly in order to employ the necessary edits to solve the caption '''New Annotations'''annotation issue.
If the user has both Edit Field in Annotation Mode Roles and View and Create Annotation permissions then, when they click on * Clicking into a field caption which has already has ''no previous annotations, ''' '''''will allow them to create a New Annotation. * Clicking into a field caption which ''does have previous annotations ''will allow them to '''Modify '''the field - they would see a small icon are then presented with the caption the '''Reply/ModifyEdit Field ''' and screen, but their ability to edit the individual field is controlled by the historic annotations displayedassociated [[Field Permissions]]. * The '''Edit Field '''functionality is only relevant when the record is on [[Image:AnnotationEditFieldButton.pngStatus Lock|borderlocked on status]]and the user has '''View Annotations '''permissions set for their role.
If :: [[File:Annotations reply modify.png|600px|border]] In this above example, the '''Branch '''field is highlighted in orange to demonstrate that there is an Annotation against it. A user, by clicking into this field, will enable the user clicks on Annotation to pop up. They will see the content of the Annotation, the creator of the Annotation (unless the '''New AnnotationsAnonymize Creator ''' or functionality has been permissioned), the date and time stamp, and the '''Reply/ModifyModify ''' button then they will see a Field Value option in the New Annotation screen.
[[Image* '''Note:AnnotationEditFieldScreen '''If the user only has '''View '''permissions and not '''View and Create Annotation '''permissions, they will not be able to access the '''New Annotation '''or see the '''Reply/Modify '''buttons against individual fields, although they will automatically see the Annotations tab along the left hand side of the screen.png|900px|border]]
A user who clicks into the '''Reply/Modify '''button will enable a pop-up to appear:
If they edit the Field Value and click Save then :: [[File:Annotations modifying.png|800px|border]]The previous annotation(s) will appear at the value stored against bottom of the field will be updated accordinglywindow.
===Review History===To change the '''Field Value, '''simply select the '''binoculars icon '''to look up different fields and to select a changed one. In this example, since the previous annotation notes that the branch is incorrect, the user could look up into the '''Field Value '''to select the correct branch and '''Save '''the change.
===Revision History===The '''Revision History History '''feature will list the full annotation history in one place. The This history is updated each time when changes are submitted through the Annotation [[Submit & Save buttons|submit button]].
* '''Note: '''The history will show both when record must be under [[Status Lock]] in order for the field is edited and when Annotation Submit button to appear on the record is submittedpage.
The ability to To access the history, click the '''Options '''button on the top left of the page. A drop-down of available features will appear - click on '''Revision History section is controlled by the [[UTA_Settings_-_Security#View_Revision_History|UTA Security Settings]]. '''
The history will show both when the field is edited and when the record is submitted. A user's ability to access the Revision History section is available controlled by clicking on the Options section at the top of the [[UTA Settings - Security|UTA record, then clicking on the resulting Revision History sectionSecurity Settings]].
:: [[File:Annotation revision history.png|400px|border]]
==See Also==
* [[Notes Overview]]
[[Category:Annotations]]
