/
Managing Call Annotations_deprecated

Managing Call Annotations_deprecated

By Dean Lawrence (Unlicensed)
Nov 22, 2018

Introduction/Purpose

A solution is required that allows for the addition of written comments (Annotation Value) as annotations that are associated to an audio recording. Annotations can only be added to designated annotation fields (annotation Header) which is a shared value across any call. A call may have multiple Annotations Values written by multiple users, but an annotation value is always specific to a single call. Annotation Headers are shared across multiple calls.

Annotation Values can be edited and deleted, both operations are restricted by user type.

Annotation Headers can be edited and deleted, both operations are restricted by user type.

The high-level ERD showing the relationships between Calls, Annotations and Headers is...



As can be seen, a Call can have none or many Annotations, and an Annotation must be related to one and only one Call. Each Annotation must have one and only one Heading, and a Heading might be used in none or many Annotations.

API Endpoints

The architecture team have determined that two endpoints will need developing to add an annotation to the call...

/api/annotateAdd

This will add a correctly formed annotation to the call. It will have no other effect other than to add the annotation.

/api/annotateSingle

This will add a correctly formed annotation to the call database and will delete all previous annotation from the call. For example if a call has two offset annotations F1, and F2 and three non-offset annotations N1, N2, and N3 stored against it, after the /api/annotateSingle endpoint has been called passing in the details of a new non-offset annotation, N4, the call will have no offset annotations and only 1 non-offset annotation, N4, stored against it; Annotations F1, F2, N1, N2, and N3 will have been deleted from the call.

Deleting an annotation is - as described below - not a true deletion. The database records will be amended to show the annotations as disabled, but they will remain in the database. Annotations that are marked as disabled are not visible in the user interface, so to the user, they will appear to have been deleted, however they are still present in the database.

Potential Actors/Roles

Call Agent: A user with appropriate permissions to be able to add an annotation to a live call they are current taking from a caller. Ability to edit and delete their own annotations.

Call Supervisor: A user with appropriate permission to be able to add annotation retrospectively to a call that has already happened or a call they are listening in on. Potentially also permission to edit & delete existing annotation content which they did not create.

System Administrator: A user with appropriate permission to be able to create, edit and delete Annotation Fields.

Automated System: A "user" that is an automated process that can automatically add Annotation values to a call.

Use Cases

  1. Create a new annotation header
  2. Update a new annotation header
  3. Delete an annotation header
  4. Add an annotation to a call currently being recorded (these are known as "Offset Annotations").
  5. View offset annotations
  6. Update an existing offset annotation
  7. Delete an offset annotation
  8. Add an annotation to a call selected from a list of existing calls (these are known as "Non-Offset Annotations").
  9. View non-offset annotations
  10. Update an existing non-offset annotation
  11. Delete a non-offset annotation

Use Case Details

1. Create a new annotation header

Actors

System Administrator

Description

The System Administrator can select an annotation and will see the option to "manage headers" (actual wording and UI element to be decided).

When the System Administrator selects the "manage headers" UI element, the Manage Headers pop-up appears. A list of existing headings will be displayed, along with a "New Header" text entry UI element, and an "Add" UI element (a button for example).

The initial focus is on the "New Header" text entry box, so the System Administrator can start typing in the new heading. The System Administrator can see if the new heading they have typed in already exists so they do not add a duplicate heading.

When the System Administrator selects the "Add" UI element, the heading will be appended to the list of existing headings displayed in the pop-up, and the heading will be written to the database, along with an audit record indicating that a new heading has been created. 

Pre-conditions

  1. The System Administrator must have permission to create an Annotation Header.
  2. The Annotation Header being added must not be present in the database.

Post-Conditions

  1. The Annotation Header must be stored in the database.
  2. The Annotation Header text must only exist once in the database.
  3. The Annotation Header Text must contain an alphanumeric value.
  4. The Annotation Header must be available to be used when adding, viewing, updating or deleting an annotation.

2. Update a new annotation header

Actors

System Administrator

Description

The System Administrator can select an annotation and will see the option to "manage headers" (actual wording and UI element to be decided).

When the System Administrator selects the "manage headers" UI element, the Manage Headers pop-up appears. A list of live existing headings will be displayed. When the System Administrator selects a heading in the existing headings list, the heading text appears in a text box and the System Administrator can amend the text of the heading. No duplicate headings are allowed to be entered and at least one alphanumeric character must be present (so a blank heading cannot be created).

The System administrator can see if the heading text they have typed in already exists so they do not add a duplicate heading.

When the System Administrator selects the "Update" UI element, the heading they have typed in will be added to the list of existing headings displayed in the pop-up, and the heading initially selected is shown as disabled. All annotations that have been written and stored that use the old heading must now show the new heading whenever a Call Agent or Call Supervisor views those annotations.

No headings are to be deleted from the database. Therefore when updating a header, the heading initially selected is marked as disabled in the database, and the heading typed in by the System Administrator is added to the database as though it were new. For System Administrators the existing headers list shows both enabled (live) headings and disabled (deleted) headings...

Only System administrators can view both enabled and disabled headings. Other users can only see enabled headings, so for example, Call Agents and Call Supervisors will only see the following headings when creating annotations...

An audit record is written indicating that a heading has been updated.

Pre-conditions

  1. The System Administrator must have permission to update an Annotation Header.
  2. The Annotation Header being updated must be present in the database.

Post-Conditions

  1. The original Annotation Header be stored as disabled in the database.
  2. The original Annotation Header must not be available to be used when adding, updating or deleting an annotation.
  3. The original Annotation Header must be available to be used when viewing an annotation that was created with, or updated to use, the original Annotation Header.
  4. The new Annotation Header must be stored in the database.
  5. The new Annotation Header text must only exist once in the database except where it matches a disabled Annotation Header.
  6. The new Annotation Header Text must contain an alphanumeric value.
  7. The new Annotation Header must be available to be used when adding, viewing, updating or deleting an annotation.

3. Delete an annotation header

Actors

System Administrator

Description

The System Administrator can select an annotation and will see the option to "manage headers" (actual wording and UI element to be decided).

When the System Administrator selects the "manage headers" UI element, the Manage Headers pop-up appears. A list of live existing headings will be displayed. When the System Administrator selects a heading in the existing headings list and then selects the "Delete" UI element, the heading they have selected will be shown as disabled in the list of existing headings.

Any annotations that use the deleted header are shown with the deleted heading, but the deleted heading cannot be used for new annotations.

No headings are to be deleted from the database. Therefore when deleting a header, the heading selected is marked as disabled in the database For System Administrators the existing headers list shows both enabled (live) headings and disabled (deleted) headings. For example if Royalties is deleted the System Administrator will see


Other users can only see enabled headings, so Call Agents and Call Supervisors will only see the following headings after the System Administrator has deleted Royalties

An audit record is written indicating that a heading has been deleted.

Pre-conditions

  1. The System Administrator must have permission to delete an Annotation Header.
  2. The Annotation Header being deleted must be present in the database.

Post-Conditions

  1. The Annotation Header must be stored as disabled in the database.
  2. The Annotation Header must not be available to be used when adding, updating or deleting an annotation.
  3. The original Annotation Header must be available to be used when viewing an annotation that was created with, or updated to use, the deleted Annotation Header.

4. Offset Annotations -Adding Annotation to a Call Being Recorded

Actors

Call Agent

Call Supervisor

Automated System

Description

The Call Agent or Call Supervisor is listening to a live call, which is being recorded, and they want to add an annotation to the call at that particular moment in time.

Selecting the "Annotate Now" button (actual text and element type to be confirmed) will open the annotations pop-up page to allow the Call Agent or Call Supervisor to add a new annotation.

In the annotations pop-up all annotations created for that call will be displayed in a chronological list oldest at the top of the list, newest at the bottom.

The Call Agent or Call Supervisor must select a "header", from a list of headers. Only one header can be chosen for each new annotation.

Once a header has been chosen the Call Agent or Call Supervisor is able to type in the new annotation text and select the Add" button. The existing annotations will be moved up and the new annotation added to the bottom of the list.

When the Call Agent or Call Supervisor has added the annotation they close the pop-up and are returned to their previous screen, which will now show the annotation at the correct point in time. As screen space is limited, only the heading that was chosen will be displayed...

Call Agents or Call Supervisors can see all Offset Annotations on the audio wave regardless of who created them originally.

Selecting the Annotation shown on the audio waveform, will display the annotation value in the annotation popup. From here the Call Agent can update or delete the annotation if the annotation was added by themselves. A Call Supervisor can update or delete the annotation regardless of who created them originally [TO BE CONFIRMED].

Annotation information includes...

  • Data - [String] 20,000 truncated character length
  • Callid
  • DateTime - annotation created date
  • The Call Supervisor's user ID
  • Offset - Capture time from inception of call recording.

An audit record is written indicating that a new offset annotation has been created.

Pre-conditions

  1. The Call Agent or Call Supervisor must have permission to create an annotation.

Post-Conditions

  1. The Annotation must have an Annotation Header.
  2. The Annotation must be stored in the database.
  3. The Annotation must have a value.
  4. The Annotation value must be alphanumeric or contain basic symbols.
  5. The Annotation Offset must contain a numeric value of the time in seconds where Annotation has been added to the call audio
  6. The Annotation must be available to be used when viewing, updating or deleting the annotation.

5. View offset annotations

Actors

Call Agent

Call Supervisor

Description

Call Agents and Call Supervisors can see the details of an annotation by clicking on the specific offset they wish to view. For example they can click on the "Profanity 00:23:18" offset...


They are then taken to the Display Annotations pop-up where they will be shown the full text of the annotation value.

Call Supervisors can see the offset annotations for any call, including ones they are listening in on. Again, clicking the relevant offset will open up the annotations pop-up where they can see the annotation text.

6. Update an existing offset annotation

Actors

Call Agent

Call Supervisor

Description

Call Agents can see all of the offset annotations on a call. Clicking the relevant offset will open up the annotations pop-up where they can see the annotation text.

Call Agents can only change annotations they have created previously.

The Call Agent can change the heading or the annotation text, or both, before selecting the "Update Annotation" UI element and the annotation will be updated in the pop-up display and the database.

Call Supervisors can see the offset annotations for any call, including ones they are listening in on, and they can update any annotation on any call.

Clicking the relevant offset will open up the annotations pop-up where they can see the annotation text. The Call Supervisor can change the heading or the text, or both, before selecting the "Update Annotation" UI element and the annotation will be updated in the pop-up display and the database.

An audit record is written indicating that an offset annotation has been updated.

Pre-conditions

  1. The Call Agent must have permission to update their own annotation.
  2. The Call Supervisor must have permission to update any annotation.
  3. The Annotation must exist in the database.

Post-Conditions

  1. The new Annotation must have an Annotation Header.
  2. The new Annotation must be stored in the database.
  3. The new Annotation must have a value.
  4. The new Annotation value must be alphanumeric or contain basic symbols.
  5. The new Annotation must be available to be used when viewing, updating or deleting the annotation.
  6. The original annotation is no longer available in the database.

7. Delete an offset annotation

Actors

Call Agent

Call Supervisor

Description

Call Agents can only delete annotations they have created previously. Clicking the relevant offset will open up the annotations pop-up where they can see the annotation text. They can select the "Delete Annotation" UI element and the annotation will be deleted from the annotations list and the audio wave-form. The annotation in the database is flagged as deleted to prevent it from being displayed but the record is retained in the database.

Call Supervisors can delete any annotation regardless of who created it originally. Clicking the relevant offset will open up the annotations pop-up where they can see the annotation text. They can select the "Delete Annotation" UI element and the annotation will be deleted from the annotations list and the audio wave-form. The annotation in the database is flagged as deleted to prevent it from being displayed but the record is retained in the database.

An audit record is written indicating that an offset annotation has been deleted.

Pre-conditions

  1. The Call Agent must have permission to delete their own annotation.
  2. The Call Supervisor must have permission to delete any annotation.
  3. The Annotation must exist in the database.

Post-Conditions

  1. The deleted annotation is stored in the database.
  2. The deleted annotation is not available for viewing.
  3. The user interface will contain nothing to indicate the deleted annotation still exists in the database

8. Adding a New Non-Offset Annotation to an Existing Call

Actors

Call Agent

Call Supervisor

Automated System

Description

The Call Agent or Call Supervisor has the Search and Replay application open, showing a list of existing calls. They can see if an annotation exists because there will be an icon of a speech bubble in the icons column to the left of the call details...

Selecting the "+" icon or the speech bubble icon will open the annotations pop-up page to allow the Call Agent or Call Supervisor to add new annotations or view historical annotations.

In the annotations pop-up all annotations created for that call will be displayed in a chronological list oldest at the top of the list, newest at the bottom.

The Call Agent or Call Supervisor must select a "header", from a list of headers. Only one header can be chosen for each new annotation.

Once a header has been chosen the Call Agent or Call Supervisor is able to type in a new annotation and select the Add" button. The existing annotations will be moved up and the new annotation added to the bottom of the list.

When the Call Agent or Call Supervisor has added the annotation they close the pop-up and are returned to their list of existing calls. This list will be amended in the following ways...

If this is the first annotation added to a call, a speech bubble icon will be displayed against the call indicating the call now has annotations.

  • A new column will be added to the far-right of the Search and Replay application calls list.The column title will be the header chosen when adding the annotation.
  • The first few characters of the annotation text will appear in the cell created at the intersection of the call and the new column.

Annotation information includes...

  • Data - [String] 20,000 truncated character length
  • Callid
  • DateTime - annotation created date
  • The Call Supervisor's user ID
  • Offset - always NULL for Non-Offset Annotations created in the Search and Replay application

Pre-conditions

  1. The Call Agent or Call Supervisor must have permission to create an annotation.

Post-Conditions

  1. The Annotation must have an Annotation Header.
  2. The Annotation must be stored in the database.
  3. The Annotation must have a value.
  4. The Annotation value must be alphanumeric or contain basic symbols.
  5. The Annotation Offset must be NULL
  6. The Annotation must be available to be used when viewing, updating or deleting the annotation.

9. View non-offset annotations

Actors

Call Agent

Call Supervisor

Description

Call Agents or Call Supervisors can see the non-offset annotations for any call.

The Call Agent or Call Supervisor has the Search & Replay Application open, displaying a list of calls. Those calls with non-offset annotations will have an "A" icon in the icons bar on the left of each call row.

Clicking the "A" against the relevant call will open up the annotations pop-up where they can see the annotation text.


10. Update an existing non-offset annotation

Actors

Call Agent

Call Supervisor

Description

The Call Agent or Call Supervisor has the Search & Replay Application open, displaying a list of calls. Those calls with non-offset annotations will have an "A" icon in the icons bar on the left of each call row.

Call Agents can see the non-offset annotations for a call but they can only update annotation they created originally. Clicking the "A" against the relevant call will open up the annotations pop-up where they can see the annotation text. The Call Agent can update the heading for the annotation or the annotation text, or  both, but only if the annotation selected was created by the Call Agent originally. They can select the "Update Annotation" UI element and the annotation will be updated in the annotations list. The annotation in the database is updated.

Call Supervisors can update the non-offset annotations for any call. Clicking the "A" against the relevant call will open up the annotations pop-up where they can see the annotation text. The Call Supervisors can update the heading for the annotation or the annotation text, or  both, regardless if who originally created the annotation. They can select the "Update Annotation" UI element and the annotation will be updated in the annotations list. The annotation in the database is updated.

An audit record is written indicating that an non-offset annotation has been updated.

Pre-conditions

  1. The Call Agent must have permission to update their own annotation.
  2. The Call Supervisor must have permission to update any annotation.
  3. The Annotation must exist in the database.

Post-Conditions

  1. The new Annotation must have an Annotation Header.
  2. The new Annotation must be stored in the database.
  3. The new Annotation must have a value.
  4. The new Annotation value must be alphanumeric or contain basic symbols.
  5. The new Annotation must be available to be used when viewing, updating or deleting the annotation.
  6. The original annotation is no longer available in the database.

11. Delete an offset non-offset annotation

Actors

Call Agent

Call Supervisor

Description

The Call Agent or Call Supervisor has the Search & Replay Application open, displaying a list of calls. Those calls with non-offset annotations will have an "A" icon in the icons bar on the left of each call row.

Call Agents can only delete non-offset annotations on a call that they created originally. Clicking the "A" against the relevant call will open up the annotations pop-up where they can see the annotation text. Selecting the "Delete Annotation" UI element, the annotation will be updated in the pop-up display and the database.

Call Supervisors can delete any non-offset annotations for a call. Clicking the "A" against the relevant call will open up the annotations pop-up where they can see the annotation text. Selecting the "Delete Annotation" UI element, the annotation will be updated in the pop-up display and the database.

Deleted annotations are no longer view-able.

Deleted Annotations are not recoverable.

An audit record is written indicating that an offset annotation has been deleted.

Pre-conditions

  1. The Call Agent must have permission to delete their own annotation.
  2. The Call Supervisor must have permission to delete any annotation.
  3. The Annotation must exist in the database.

Post-Conditions

  1. The deleted annotation is stored in the database.
  2. The deleted annotation is not available for viewing.
  3. The user interface will contain nothing to indicate the deleted annotation still exists in the database

Dependencies

All requirements related to the auditing of creation, updates and deleting of both values and Headers will be cared for as part of the auditing solution. :Insert Link:

Whiteboard Session 2018-11-09 11:30 - 12:00 Gotham

Attendees...

  • Dean Lawrence
  • Simon Jolly
  • Yusuf Limalia

Simon drew out the following...

From this and discussion in the session, the following requirements have been identified...

  1. Annotations with an offset of NULL seconds are non-offset annotations. These apply to the whole call
  2. Annotations with an offset of >0 seconds are offset annotations. These annotations apply to the specific point in the call.
  3. A call can store zero-to-many annotations.
  4. The annotations will have one header.
  5. Headers do not have to be unique for any annotations stored for a call. So, for example, a call can have a non-offset annotation value of "Refund" for the heading "Notes", and the same call can have another non-offset annotation value of "Rude" for the heading "Notes"; a further offset annotation value of "Bomb Threat" can also be added again using the heading "Notes".
  6. Developers will use two endpoints when adding annotations; /api/annotateAdd and /api/annotateSingle (these names may be subject to change).
  7. The /api/annotateAdd endpoint will take a heading, an annotation value and an offset (which may be null for non-offset annotations) and will store the annotation on the call, along with any annotations already stored against the call. For example if there are three annotations stored already, one for the heading "Profanity", and two for the heading "notes", calling the /api/AnnotateAdd with the heading "Profanity" will result in the call having four annotations; two for "notes" and two for "Profanity".
  8. The /api/annotateSingle endpoint will take a heading, an annotation value and an offset (which may be null for non-offset annotations) and will store the annotation on the call, but will delete any other annotations already stored against the call. For example if there are three annotations stored already, one for the heading "Profanity", and two for the heading "notes", calling the /api/AnnotateSingle with the heading "Profanity" will result in the call having one annotation only. This will be the one added via the /api/annotateSingle endpoint with the heading "Profanity".
  9. When a heading is updated, no changes to annotation added using the original heading value will be made. No historical updates will be made.
  10. When a heading is deleted, it is only disabled so it can no longer be selected. Any annotations added using the original heading value will be retained.
  11. During playback of a call with offset annotations, the annotations will be shown as labels on the audio waveform at the time of the offset.
  12. Where more than one offset annotation is added for the same offset time, or where a group of offset annotations are added within a short period of times, the annotation labels will be congested on the playback so a decision how to handle these must be made.

Whiteboard Session 2018-11-20 15:00 - 16:00 Gotham

Attendees...

  • Dean Lawrence
  • Simon Jolly

When will the annotateSingle endpoint be used? - When, and only when, SJ uses it.

What will the user do to call annotateSingle endpoint? - The user will not be able to perform any UI tasks that will call that endpoint.

Clarify when changing the header will call annotateSingle endpoint and when it will not. - It will not, at least from the user's perspective. If SJ uses it he can resolve those questions himself.

Isn't there a danger that the users will not amend annotation headers if they know they will be deleting all of the annotations recorded previously, and they will instead retain the incorrect heading simply to retain any annotations? NO, because they will not be using it. Only SJ or people he allows to use the annotateSIngle endpoint

Simon verified that the ERD is correct.

SJ confirmed that when the heading is changed in the UI then all the annotations currently using that heading will have their headings changed to the new heading.

He said he wants the single endpoint delivering in the December release, but it will not be accessed from the user's UI. There are no steps in the UI that will lead up to a call to the single endpoint. SJ will use it should he wish to do so under his own volition.

The UI will only call the "annotateAdd" endpoint - at least in the December release, but SJ wants the annotateSingle endpoint delivering in the December release.

SJ confirmed that both Call Agents and Call Supervisors can both add non-offset annotations, not just Call Supervisors.

Dynamic Demonstration.

The Demo Data spreadsheet below contains VBA mock-ups of the annotations process, and a number of different layouts are shown...

Annotate Calls Demo.xlsm

Mock-ups

An example of adding annotations is shown below...


Adding Annotations to Recording sequence is shown in the following...

The Balsamiq project of the above, with interactive links is available here... Annotations.bmpr

The Excel spreadsheet contains a VBA 

Annotation Tags

The Balsamiq project highlights the adding of tags, which the Invision screen shots do not.

The System User must select a tag when adding an annotation. The tag is stored along with the annotation. This will allow annotations to be searched more efficiently, as a System User can search for all annotations that have a particular tag.

If the System User cannot see a suitable tag to use when adding an annotation, they can add a new tag. This will need to be an Administrator function, or a specific System User who has been granted the permission to create a tag.

Technical Implementation Details

These can be found here Annotate a Call





Add label